@timber-js/app 0.2.0-alpha.185 → 0.2.0-alpha.187

package/dist/shared/static-platform-files.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Platform files the static build is allowed to overwrite in the output.
+ *
+ * The build merges two trees into the deployed directory — the client bundle
+ * (which carries everything the user put in `public/`) and the pre-rendered
+ * site. That merge otherwise refuses overlaps, because a silent overwrite
+ * leaves one of two artifacts deployed with nothing recording which
+ * (TIM-1266).
+ *
+ * These names are the exception, and only because the pre-rendered copy is
+ * *derived from* the one it replaces rather than competing with it:
+ * `plugins/static-build.ts` reads `public/_redirects` and writes the
+ * generated rules plus the user's, so the winner is a superset of the loser.
+ *
+ * That holds only for a file the current pass produced, which is why
+ * `cleanConditionalArtifacts` deletes a previous build's `_redirects` before
+ * generation: written only when a pass finds redirects, it would otherwise
+ * survive into a pass that produced nothing and claim an exemption it no
+ * longer earns.
+ *
+ * `_headers` is NOT here. It is not written into the pre-rendered tree at
+ * all — adapters generate it directly into the output, folding in the
+ * user's copy as they go (TIM-1326).
+ *
+ * Declared once so the code that performs the merge and the code that
+ * produces the merged file cannot disagree about which names are exempt.
+ *
+ * Isomorphic: no server, client, or build-time imports.
+ */
+/** Platform redirect rules (Cloudflare Pages, Netlify). See TIM-1245/TIM-1249. */
+export declare const REDIRECTS_FILE = "_redirects";
+/** Platform header rules (Cloudflare Pages, Netlify). See TIM-1241/TIM-1326. */
+export declare const HEADERS_FILE = "_headers";
+/**
+ * Where a user authors platform files. Stated once because two modules read
+ * from here — `plugins/static-build.ts` for `_redirects`, adapters for
+ * `_headers` — and they must look in the same place.
+ *
+ * Both read the **project source**, never the build output. The generated
+ * file lands under the same name in the output directory, so a reader aimed
+ * there would fold the previous build's generated rules back in and compound
+ * them on every rebuild.
+ */
+export declare const USER_PLATFORM_DIR = "public";
+/** Output-relative paths whose pre-rendered copy subsumes the `public/` one. */
+export declare const USER_MERGED_PLATFORM_FILES: readonly string[];
+/**
+ * Output paths the framework writes itself, which no route may claim.
+ *
+ * These are written outside the per-entry writer — `_redirects` after
+ * generation, `_headers` by the adapter after the copy — so the collision
+ * tracker never sees them and a route rendering to one of these paths is
+ * overwritten with nothing recording it.
+ *
+ * Reserved rather than tracked, because there is no version of "serve a route
+ * at `/_headers`" that works: Cloudflare Pages and Netlify read these two
+ * files themselves and never serve them, so the route is unservable however
+ * the conflict is resolved.
+ *
+ * That justification is per-file, not per-mechanism. `.nojekyll` is written
+ * the same way and is deliberately NOT here: only the `github-pages` target
+ * writes it, and everywhere else `/.nojekyll` is an ordinary servable path,
+ * so reserving it globally would refuse a valid Cloudflare site. Its write
+ * site skips the write when a file is already there instead — GitHub Pages
+ * only cares that the file exists.
+ *
+ * Same reasoning as the synthetic 404 entry using an internal urlPath so a
+ * real `/404` route cannot collide with `404.html`.
+ */
+export declare const RESERVED_OUTPUT_PATHS: readonly string[];
+//# sourceMappingURL=static-platform-files.d.ts.map

package/dist/shared/static-platform-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-platform-files.d.ts","sourceRoot":"","sources":["../../src/shared/static-platform-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,kFAAkF;AAClF,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C,gFAAgF;AAChF,eAAO,MAAM,YAAY,aAAa,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,WAAW,CAAC;AAE1C,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAAqB,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAAmC,CAAC"}

package/docs/api/30-api-server.mdx

@@ -161,7 +161,7 @@ interface RouteContext {
 }
 ```
 
-Segment params and query params are **not** on `RouteContext`. Read them via the same ALS-backed `.get()` accessors pages use — `segmentParams.get()` from `./params` and `searchParams.get()` from `./search-params`. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+Segment params and query params are **not** on `RouteContext`. Read them the same way pages do — `getSegmentParams(SEGMENT_PATH)` (importing `SEGMENT_PATH` from the route's `./$segment` module) and `searchParams.get()` on an imported definition. For the raw query string, use `new URL(ctx.req.url).searchParams`.
 
 ### `MiddlewareContext`
 

package/docs/api/31-api-client.mdx

@@ -28,7 +28,7 @@ import { Link } from '@timber-js/app/client';
 | ------------ | ------------------- | ------------------------------------------- |
 | `href`       | `string`            | Target URL (type-checked against route map) |
 | `replace`    | `boolean`           | Use `replaceState` instead of `pushState`   |
-| `prefetch`   | `boolean`           | Prefetch on hover/viewport                  |
+| `prefetch`   | `boolean`           | Prefetch the RSC payload on hover           |
 | `onNavigate` | `OnNavigateHandler` | Intercept navigation before routing         |
 
 ### `<TimberErrorBoundary>`
@@ -60,6 +60,8 @@ router.forward();
 | `back()`        | Go back                            |
 | `forward()`     | Go forward                         |
 
+If the server answers a navigation or a `refresh()` with an error, the router hands the URL back to the server as a full page load so it can render the error page as HTML with the right status code. That applies to back/forward too. None of these methods report the failure to your code — there is nothing to catch, and nothing to render a fallback for.
+
 ### `usePathname()`
 
 Returns the current pathname as a string.
@@ -97,7 +99,7 @@ const pending = usePendingNavigation();
 Per-link pending state. Must be used inside a `<Link>` component's children.
 
 ```tsx
-const { pending } = useLinkStatus();
+const { isPending } = useLinkStatus();
 ```
 
 ### `useSegmentParams(segmentPath?)`

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

@@ -45,9 +45,8 @@ Note: `z.coerce.*` schemas declare input `unknown`, so a coerce schema without `
 | `.useQueryStates(opts?)`  | Client hook — read and update typed search params      |
 | `.extend(codecs)`         | Add additional params                                  |
 | `.pick(...keys)`          | Create a subset                                        |
-| `.serialize(values)`      | Convert typed values to URL search string              |
 | `.href(base, values)`     | Build a full URL with params                           |
-| `.toSearchParams(values)` | Convert to `URLSearchParams`                           |
+| `.buildSearchParams(values)` | Serialize to a query string — pass to `<Link searchParams>` |
 | `.codecs`                 | Read-only codec map                                    |
 | `.urlKeys`                | Read-only URL key alias map                            |
 
@@ -110,31 +109,52 @@ The codec protocol shared across search params, segment params, and cookies. See
 interface SearchParamCodec<T> {
   parse(value: string | string[] | undefined): T;
   serialize(value: T): string | null;
+  urlKey?: string;
+  // optional total entry point — preferred over parse when present
+  parseServerSide?(value: string | string[] | undefined): T;
 }
 ```
 
+`parse` receives the **raw** URL value — `string | string[] | undefined` — because a param may be absent (`/products`) or repeated (`?q=a&q=b`). A codec must handle all three.
+
+If handling all three in `parse` is awkward — as it is for a nuqs parser, whose `parse` is written for a present scalar — publish `parseServerSide` instead. Timber calls it wherever it invokes the codec, and its return type is the field's type: a codec that answers `null` for an absent param is a `SearchParamCodec<T | null>`.
+
 Compatible codecs:
 
-- **Zod/Valibot/ArkType schemas** — auto-detected via Standard Schema
-- **nuqs parsers** — `parseAsInteger`, `parseAsString`, `parseAsBoolean`
+- **Zod/Valibot/ArkType schemas** — auto-detected via Standard Schema. Total over absent and repeated input, so this is the safe default.
 - **Custom** — any object implementing the interface
+- **nuqs parsers** — total through timber, with one exception. See below.
+
+## Parsers come from nuqs
+
+Timber does not ship or re-export `parseAs*` parsers. Import them from [nuqs](https://nuqs.47ng.com/), which is a peer dependency; timber ships the wrappers (`withDefault`, `withUrlKey`) and the schema bridge.
+
+nuqs checks whether a param is present before calling `parse`, so a parser's `parse` assumes a present scalar. Timber calls the parser's `parseServerSide` instead — nuqs's own adapter for the raw URL value — so every **single**-value parser is total:
+
+| Raw value             | Result                                                        |
+| --------------------- | ------------------------------------------------------------- |
+| absent (`/products`)  | `null`, or the parser's own default if it declares one        |
+| repeated (`?v=a&v=b`) | the **first** value, matching `URLSearchParams.get()`         |
+| present               | whatever the parser returns; if it **throws**, `null`         |
 
-## Built-in Codecs
+So `?page=1&page=2` gives `1`, `parseAsBoolean` on a missing `?debug=` gives `null` rather than an HTTP 500, and `parseAsString` on `?q=a&q=b` gives `'a'` rather than an array its type forbids.
 
-| Export                         | Description                 |
-| ------------------------------ | --------------------------- |
-| `parseAsString`                | `string \| null`            |
-| `parseAsInteger`               | `number \| null`            |
-| `parseAsFloat`                 | `number \| null`            |
-| `parseAsBoolean`               | `boolean \| null`           |
-| `parseAsStringEnum(values)`    | Enum `T \| null`            |
-| `parseAsStringLiteral(values)` | Literal `T[number] \| null` |
+A present value is not validated for you — each parser decides. `parseAsBoolean` on `?v=maybe` is `false`, and `parseAsInteger` on `?v=12abc` is `12`. Use a schema when you need the value rejected rather than coerced.
+
+The exception is `parseAsNativeArrayOf`, nuqs's *multi*-value parser for repeated keys. It is **not usable in `defineSearchParams`**: its `parse` is declared over `readonly string[]`, so the field is a compile error, and forcing it through leaves the client hook reading it as empty. Use an array schema for repeated keys. Tracked as TIM-1355.
+
+Two consequences worth knowing:
+
+- **`parseAsArrayOf` reads one key, not repeated keys.** It is a comma-separated list inside a single value, so `?tags=a,b` gives `['a','b']` but `?tags=a&tags=b` gives `['a']`. For repeated keys use an array schema — `tags: z.array(z.string()).default([])` reads both `?tags=a` and `?tags=a&tags=b`.
+- **`parseAsJson` requires a validator argument** — `parseAsJson(z.object({ … }).parse)`. Called bare it does not type-check, and at runtime returns `null` for every value.
+
+A field typed by a bare parser is nullable (`parseAsString` → `string | null`). Use `withDefault()` — timber's or the parser's own — to make it non-nullable.
 
 ## Codec Wrappers
 
 ### `withDefault(codec, value)`
 
-Wrap a codec to replace `null` with a default value.
+Wrap a codec to supply a value whenever the inner codec produces none — `null` or `undefined`. The field is non-nullable.
 
 ```ts
 import { withDefault } from '@timber-js/app/search-params';
@@ -142,13 +162,15 @@ import { parseAsInteger } from 'nuqs';
 const page = withDefault(parseAsInteger, 1); // number (never null)
 ```
 
+A **present** value is left alone, including a falsy one: `?page=0` is `0`, and `?q=` is `''`, not the default.
+
 ### `withUrlKey(codec, key)`
 
 Attach a URL key alias to a codec.
 
 ```ts
 import { withUrlKey } from '@timber-js/app/search-params';
-import { parseAsString } from 'nuqs';
-const query = withUrlKey(parseAsString, 'q');
+import { z } from 'zod/v4';
+const query = withUrlKey(z.string().nullable().default(null), 'q');
 // ?q=shoes → { query: 'shoes' }
 ```

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

@@ -107,10 +107,10 @@ Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — all optional.
 
 ## Typed Search Params
 
-When a `params.ts` file exports `searchParams`, search params are fully typed:
+Search params are typed by the definition you create and import — there is no convention file:
 
 ```ts
-// app/products/params.ts
+// app/products/search-params.ts — any module you like
 import { defineSearchParams } from '@timber-js/app/search-params';
 import { z } from 'zod/v4';
 
@@ -135,7 +135,7 @@ export async function GET(ctx: RouteContext) {
 }
 ```
 
-Segment params and query params are read via `segmentParams.get()` / `searchParams.get()` from the colocated `params.ts` / `search-params.ts` — the same accessors pages use. For the raw query string, use `new URL(ctx.req.url).searchParams`.
+Query params are read via `searchParams.get()` on an imported definition — the same accessor pages use. Segment params come from `getSegmentParams(SEGMENT_PATH)`. For the raw query string, use `new URL(ctx.req.url).searchParams`.
 
 ### `MiddlewareContext`
 

package/docs/api/36-cli.mdx

@@ -9,7 +9,7 @@ slug: 'cli'
 timber.js provides four commands. All are thin wrappers around Vite with timber-specific behavior.
 
 ```tsx
-timber < command > [--config<path>];
+timber < command > [--config<path>][--project<path>];
 ```
 
 ## Commands
@@ -40,7 +40,7 @@ To override the default, use any of the following (highest precedence first):
 1. `server.port` in `vite.config.ts`
 2. `PORT=4000 timber dev` — the `PORT` environment variable
 
-> **Note:** `timber dev --port 4000` is an error, not a silent no-op. The timber CLI only accepts `--config` — use `PORT` or `server.port` to change the port.
+> **Note:** `timber dev --port 4000` is an error, not a silent no-op. `timber dev` accepts only `--config` — use `PORT` or `server.port` to change the port.
 
 When you set the port explicitly, timber **does not** auto-bump — a conflict produces an `EADDRINUSE` error so you find out immediately rather than connecting to the wrong port. This same behavior applies to `timber preview` and the production Node preview server.
 
@@ -84,13 +84,39 @@ Always run `timber build` before `timber preview`.
 
 ### `timber check`
 
-Validate types and routes without producing build output.
+Validate routes and types without producing build output.
 
 ```bash
 timber check
+timber check --config ./custom-vite.config.ts --project ./tsconfig.build.json
 ```
 
-Runs TypeScript type checking via `tsgo --noEmit`. Useful in CI pipelines and pre-commit hooks to catch type errors without a full build.
+Two passes, in order:
+
+1. **Routes.** Resolves your project through Vite exactly as `timber build` does — same root, app directory and `pageExtensions`, same `production` mode and `NODE_ENV`, and including config passed inline to `timber()` in `vite.config.ts`. A config that branches on `mode` or reads `.env.production` therefore resolves the same way under both commands. It then scans, runs the route convention linter, and regenerates the route types (`.timber/timber-routes.d.ts`, `.timber/segment-types.d.ts`, `timber-env.d.ts`). Convention *errors* — the proven-fatal misconfigurations that also fail `timber build`, such as an `error.tsx` that is a server component — fail the command. Warnings print and do not.
+2. **Types.** `tsgo --noEmit`, run from the root the route pass resolved — so it type-checks the same project whose routes were just validated, and finds the declarations that pass just wrote. A relative `--project` is interpreted from the directory you ran the command in.
+
+Codegen runs first on purpose: the generated declarations are what type `<Link href>`, `useSegmentParams()`, and `MiddlewareContext`. On a fresh clone that has never run `timber dev` or `timber build` they do not exist yet, so a bare type check would report errors about correct code.
+
+Your `tsconfig.json` must pull in `timber-env.d.ts` — that file is what references the generated route map. If your `include` lists only source directories, add it:
+
+```json
+{
+  "include": ["app", "*.config.ts", "timber-env.d.ts"]
+}
+```
+
+`timber check` warns when the generated types are not part of the resolved program, because the type check would otherwise pass while measuring `<Link href>` against an empty placeholder. Projects created with `create-timber-app` are configured correctly.
+
+`timber check` requires **`@typescript/native-preview`** (which provides `tsgo`). It is an optional peer dependency — install it as a dev dependency:
+
+```bash
+pnpm add -D @typescript/native-preview
+```
+
+If it is missing, `timber check` fails with that instruction. It never passes by skipping the type check.
+
+Useful in CI pipelines and pre-commit hooks to catch type and routing errors without a full build.
 
 ### `timber init`
 
@@ -108,11 +134,12 @@ The generated `AGENTS.md` includes project structure, key imports, common patter
 
 | Flag              | Short | Description                                                                                               |
 | ----------------- | ----- | --------------------------------------------------------------------------------------------------------- |
-| `--config <path>` | `-c`  | Path to a custom Vite config file (for `dev`, `build`, `preview`) or a `tsconfig.json` path (for `check`) |
+| `--config <path>`  | `-c`  | Path to a custom Vite config file. Means the same thing for every command, `check` included. |
+| `--project <path>` |       | `timber check` only — the `tsconfig.json` to type-check.                                     |
 
-> **Note:** For `timber check`, `--config` is passed to `tsgo --project` and should point to a TypeScript config file, not a Vite config.
+> **Note:** `timber check` resolves your app through Vite, so `--config` names the Vite config there too, exactly as it does for `dev` and `build`. The tsconfig has its own flag, `--project`, spelled the way `tsc` and `tsgo` spell it. `check` needs a Vite config that lists the timber plugin and fails with an actionable message if it cannot find one.
 
-`--config` is the only flag. Any other flag produces an error rather than being silently ignored, with a hint at the supported alternative (e.g. `--port` points you to the `PORT` env var or `server.port` in `vite.config.ts`).
+Those are the only flags. Any other produces an error rather than being silently ignored, with a hint at the supported alternative (e.g. `--port` points you to the `PORT` env var or `server.port` in `vite.config.ts`). Passing `--project` to a command with no type pass is an error too, pointing you at `--config`.
 
 ## Package Manager Scripts
 

package/docs/learn/00-introduction.mdx

@@ -69,7 +69,7 @@ const [sp, setSearchParams] = searchParams.useQueryStates();
 All routing in timber is fully typed and integrated. So you can write a `<Link>` as:
 
 ```tsx
-<Link href="/blog/[slug]" segmentParams={{ slug: 'a-post' }} searchParams={{ foo: 'bar' }}>Page</Link>
+<Link href="/blog/[slug]" segmentParams={{ slug: 'a-post' }}>Page</Link>
 ```
 
 Or just normal `<a>` tags work too.

package/docs/learn/02-pages-and-layouts.mdx

@@ -94,7 +94,7 @@ Each directory is called a **segment** and can contain these files:
 | `layout.tsx`    | Persistent UI shell — wraps children, survives navigation |
 | `access.ts`     | Authorization gate — runs before the layout renders       |
 | `middleware.ts` | Pre-render hook for headers, redirects, and cache warming |
-| `params.ts`     | Typed search params definitions (see [Typed Params](/docs/typed-params)) |
+| _(none)_        | Segment param codecs live in `app/schema.ts`; search params in any module you import — see [Typed Params](/docs/typed-params) |
 | `error.tsx`     | Error boundary catching failures in this subtree          |
 | `404.tsx`       | Denial page for 404 status code (must be a client component) |
 
@@ -140,7 +140,7 @@ app/
 timber produces build errors for ambiguous route configurations:
 
 - **Duplicate convention files** — `page.tsx` and `page.jsx` in the same directory is an error, not a silent winner-by-filesystem-order
-- **Route group collisions** — two route groups in the same slot that both define a page for the same URL path are caught at build time
+- **Route collisions** — two pages (or a page and a `route.ts`) that answer the same URL are caught at build time. Routes are compared by the URLs they match, not by how they are spelled: `x/(a)/[id]/page.tsx` and `x/(b)/[slug]/page.tsx` collide, and so do `x/(a)/page.tsx` and `x/(b)/[[...rest]]/page.tsx`, since an optional catch-all also matches with zero segments. Different segment _kinds_ don't collide — `[id]` beside `[...rest]` is ordered deterministically and keeps building
 
 This behavior is deterministic regardless of filesystem `readdir` order. In Next.js, the result of these ambiguities depends on the OS and filesystem, which can produce different behavior between local development and CI.
 

package/docs/learn/05-typed-params.mdx

@@ -112,9 +112,9 @@ const params = getSegmentParams();
 
 ## Search Params
 
-Declare typed search params with `defineSearchParams`:
+Declare typed search params with `defineSearchParams` in any module, then import it where you need it. Unlike segment params, there is no convention file and nothing is scanned:
 
-```ts title="app/products/params.ts" id="search-params"
+```ts title="app/products/search-params.ts" id="search-params"
 import { defineSearchParams, withDefault } from '@timber-js/app/search-params';
 import { parseAsInteger } from 'nuqs';
 import { z } from 'zod/v4';
@@ -129,7 +129,7 @@ export const searchParams = defineSearchParams({
 ### Server Usage
 
 ```tsx title="app/products/page.tsx" use="search-params"
-import { searchParams } from './params';
+import { searchParams } from './search-params';
 
 export default async function ProductsPage() {
   const { page, sort, q } = searchParams.get();
@@ -142,7 +142,7 @@ export default async function ProductsPage() {
 
 ```tsx title="app/products/filters.tsx" use="search-params"
 'use client';
-import { searchParams } from './params';
+import { searchParams } from './search-params';
 
 export function ProductFilters() {
   const [params, setParams] = searchParams.useQueryStates();
@@ -231,7 +231,7 @@ For segment params, use the `codec` namespace:
 | `codec.catchAll(inner)` | `T[]`             | Wraps scalar codec for catch-all segments |
 | `codec.optionalCatchAll(inner)` | `T[] \| undefined` | Wraps scalar codec for optional catch-all segments |
 
-Use `withDefault()` to get a non-nullable type for search params. [nuqs](https://nuqs.47ng.com/) parsers (`parseAsIsoDate`, `parseAsJson`, `parseAsArrayOf`) are also valid codecs — they implement the same interface natively. */}
+Use `withDefault()` to get a non-nullable type for search params. [nuqs](https://nuqs.47ng.com/) parsers all work as codecs: an absent param is `null` and a repeated one takes the first value. Note that `parseAsArrayOf` reads a comma-separated list from a single key — for repeated keys (`?ids=1&ids=2`) use an array schema, e.g. `z.array(z.string()).default([])`. */}
 
 ## Composition
 
@@ -247,7 +247,7 @@ export const pagination = {
 };
 ```
 
-```ts title="app/products/params.ts"
+```ts title="app/products/search-params.ts"
 import { defineSearchParams } from '@timber-js/app/search-params';
 import { pagination } from '@/lib/search-params/pagination';
 import { z } from 'zod/v4';
@@ -264,10 +264,10 @@ Map a property name to a different URL key with `withUrlKey`:
 
 ```ts
 import { defineSearchParams, withUrlKey } from '@timber-js/app/search-params';
-import { parseAsString } from 'nuqs';
+import { z } from 'zod/v4';
 
 export const searchParams = defineSearchParams({
-  query: withUrlKey(parseAsString, 'q'),
+  query: withUrlKey(z.string().nullable().default(null), 'q'),
 });
 // ?q=shoes → { query: 'shoes' }
 ```

package/docs/learn/07-typed-routes.mdx

@@ -84,23 +84,23 @@ Add `rootDirs` so TypeScript can resolve `$segment` imports:
 
 ## Typed Search Params
 
-When a `params.ts` file exports `searchParams`, search params are fully typed throughout the stack:
+Define search params with `defineSearchParams()` in any module and import it — there is no convention file. Search params are then fully typed throughout the stack:
 
-```ts title="app/products/params.ts"
+```ts title="app/products/search-params.ts"
 import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params';
-import { parseAsInteger, parseAsString, parseAsStringEnum } from 'nuqs';
+import { parseAsInteger, parseAsStringEnum } from 'nuqs';
 import { z } from 'zod/v4';
 
 export const searchParams = defineSearchParams({
   page: withDefault(parseAsInteger, 1),
-  q: withUrlKey(parseAsString, 'search'),
+  q: withUrlKey(z.string().nullable().default(null), 'search'),
   category: z.string().nullable().default(null),
   sort: withDefault(parseAsStringEnum(['price-asc', 'price-desc', 'newest']), 'newest'),
 });
 ```
 
 ```tsx title="app/products/page.tsx"
-import { searchParams } from './params';
+import { searchParams } from './search-params';
 
 export default async function ProductsPage() {
   const { page, q, category, sort } = await searchParams.get();
@@ -108,16 +108,21 @@ export default async function ProductsPage() {
 }
 ```
 
-`<Link>` validates `searchParams` against the route's definition too:
+Pass them to `<Link>` by building them from the definition. `buildSearchParams` type-checks the values and applies the definition's codecs and URL-key aliases:
 
 ```tsx
+import { searchParams } from './search-params';
+
 <Link
   href="/products/[id]"
   segmentParams={{ id }}
-  searchParams={{ sort: 'newest', q: 'boots' }}
+  searchParams={searchParams.buildSearchParams({ sort: 'newest', q: 'boots' })}
 />
+// → /products/42?sort=newest&search=boots   (q is aliased to search)
 ```
 
+A plain object also works as an untyped escape hatch for one-off params with no definition — but it skips codecs and aliases, so do not use it for keys a definition owns.
+
 See [Typed Params](/docs/typed-params) for the full search params API.
 
 ## Codegen

package/docs/learn/11-error-handling.mdx

@@ -73,6 +73,20 @@ Priority order (innermost to outermost):
 3. `error.tsx` — catches anything unmatched
 4. Parent segments → framework default
 
+Component status files (`.tsx`, `.jsx`, `.ts`, `.js`) and `error.tsx` **must start with `'use client'`**:
+
+```tsx title="app/404.tsx"
+'use client';
+
+export default function NotFound({ status }: { status: number }) {
+  return <h1>Page not found</h1>;
+}
+```
+
+timber hands these components to its error boundary — a client component — as a prop, so a server component there cannot cross the RSC boundary. It is not a degraded error page: every page under that segment fails to render. The build catches it and names the file, so you will not discover it as a serialization error on a page you did not touch. MDX status files (`404.mdx`) are the exception — they are server components, rendered ahead of time.
+
+If nothing in the chain matches, timber renders a built-in status page: a plain document with the status code and its reason phrase, and nothing else — no request URL, no error message. It is what a static build writes to `404.html` when your app has no not-found page, so a static deploy always ships one. Add a root `app/404.tsx` (or `4xx.tsx` / `error.tsx`) to replace it.
+
 ## `error.tsx`
 
 The general error boundary. It's a client component:
@@ -99,6 +113,10 @@ export default function DashboardError({
 
 Error boundaries wrap page content inside layouts — the layout shell (nav, sidebar) stays visible when an error fires.
 
+A status page renders inside the layouts **above and including the segment it lives in**, and none below it. A root `404.tsx` serving a `deny(404)` from `app/docs/[slug]/page.tsx` renders inside the root layout only — `docs/layout.tsx` and `[slug]/layout.tsx` do not appear, because the file that matched lives above them. Co-locate the status file with the segment whose chrome you want kept: move that `404.tsx` to `app/docs/` and the docs layout comes with it.
+
+One exception: **the segment that denied never contributes its own layout**, even when it owns the matched status file. If its `access.ts` denied, that layout sits behind the failed auth check, so running it would let it fetch and serialize data the request was not allowed to see. If the layout itself called `deny()`, it threw instead of returning its chrome, so there is nothing to render. A `deny()` from a page is unaffected — the page's own layout still renders.
+
 When a `deny()` has no matching status-code file, it falls through to the nearest `error.tsx`. The component still receives a real `error` (its message is `Access denied with status <N>`), and additionally receives `status` and `dangerouslyPassData` so you can render denial-specific UI:
 
 ```tsx title="app/error.tsx"

package/docs/learn/12-client-navigation.mdx

@@ -93,8 +93,8 @@ Track per-link pending state during navigation:
 import { Link, useLinkStatus } from '@timber-js/app/client';
 
 function NavItemInner({ children }: { children: React.ReactNode }) {
-  const { pending } = useLinkStatus();
-  return <span className={pending ? 'opacity-50' : ''}>{children}</span>;
+  const { isPending } = useLinkStatus();
+  return <span className={isPending ? 'opacity-50' : ''}>{children}</span>;
 }
 
 export function NavItem({ href, children }: { href: string; children: React.ReactNode }) {

package/docs/learn/14-deploying.mdx

@@ -200,6 +200,29 @@ export default {
 
 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.