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

package/dist/server/types.d.ts

@@ -24,21 +24,26 @@ export interface MiddlewareContext {
  * `req` is the original incoming Request; `headers` is the response-headers
  * container the framework will apply to the final Response.
  *
- * Segment params and query parameters are NOT on this context — they are
- * accessed via the same ALS-backed `.get()` accessors pages use:
+ * Segment params and query parameters are NOT on this context — they are read
+ * the same way pages read them:
  *
  * ```ts
- * // app/api/users/[id]/params.ts
- * export const segmentParams = defineSegmentParams({ id: z.coerce.number() });
+ * // app/schema.ts — every dynamic segment's codec, keyed by bracket name
+ * export default defineSchema({ segmentParams: { '[id]': z.coerce.number() } });
+ *
  * // app/api/users/[id]/route.ts
- * import { segmentParams } from './params';
+ * import { getSegmentParams } from '@timber-js/app/server';
+ * import { SEGMENT_PATH } from './$segment';
  * export async function GET() {
- *   const { id } = segmentParams.get(); // typed number — 404 on bad input
+ *   const { id } = getSegmentParams(SEGMENT_PATH); // typed number — 404 on bad input
  * }
  * ```
  *
+ * For query parameters, import a `defineSearchParams` definition and call
+ * `.get()` on it.
+ *
  * See design/07-routing.md §"RouteContext", design/23-search-params.md,
- * design/40-segment-params.md.
+ * design/41-global-params.md.
  */
 export interface RouteContext {
     req: Request;

package/dist/server/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/server/types.ts"],"names":[],"mappings":"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"}

package/dist/server/utils/element-type.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Component-type validation for values loaded from route modules.
+ *
+ * Route modules are loaded dynamically, so their `default` export is
+ * `unknown`. Every construction site that wants to pass one to
+ * `createElement` narrows it through `isValidElementType` first.
+ */
+import type { ReactNode } from 'react';
+/**
+ * A React component reference loaded from a route module's default export.
+ *
+ * Loaded modules' `default` is typed as `unknown` (modules are dynamic), so
+ * call sites narrow it through `isValidElementType` (below) before treating
+ * it as a component. The signature is a callable returning `ReactNode` —
+ * TypeScript's view of every valid React component shape, including exotic
+ * components (`memo`, `forwardRef`, `lazy`) which the type system treats as
+ * callable even though their runtime values are objects with `$$typeof`
+ * markers rather than functions.
+ */
+export type LoadedComponent = (...args: unknown[]) => ReactNode;
+/**
+ * Validate that a loaded module's `default` export is something React
+ * accepts as the first argument to `createElement` — i.e. a valid component
+ * type. React doesn't export `isValidElementType` (only `isValidElement`,
+ * which checks for *elements*, not *component types*), so this mirrors
+ * React's internal check:
+ *
+ *   - functions  → function or class components
+ *   - objects with a `$$typeof` matching one of React's known component
+ *     markers → exotic components (`memo`, `forwardRef`, `lazy`, context,
+ *     suspense, client references via `@vitejs/plugin-rsc`)
+ *
+ * Strings (HTML tag names) are valid for `createElement` but never appear
+ * as a route module's default export, so they're not recognized here.
+ *
+ * Anything else (numbers, plain config objects, JSON, etc.) is rejected so
+ * the boundary wrapper is skipped rather than crashing inside React.
+ */
+export declare function isValidElementType(value: unknown): value is LoadedComponent;
+//# sourceMappingURL=element-type.d.ts.map

package/dist/server/utils/element-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-type.d.ts","sourceRoot":"","sources":["../../../src/server/utils/element-type.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,SAAS,CAAC;AA2BhE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAK3E"}

package/dist/shared/rsc-media-type.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The RSC Flight media type, and the request predicate over it.
+ *
+ * One module owns the string because two independently-written spellings of
+ * "is this an RSC request?" must agree, and the consequence of them
+ * disagreeing is cache poisoning rather than a visible bug. The Cloudflare
+ * adapter's `isRsc` decides what may enter the edge cache; the origin's
+ * pipeline decides which headers may vary the response. TIM-1269 made the
+ * adapter's `VARY_HONORED` allowlist exempt `Accept` *because* `isRsc`
+ * excludes Flight responses from the cache, and exempt the `X-Timber-*`
+ * headers *because* the origin reads them only behind its own RSC check. If
+ * one predicate is ever tightened (a real media-type parse, a
+ * parameter-aware match) and the other is not, the adapter can classify a
+ * request as a document while the origin treats it as RSC, and store a
+ * Flight payload under the document's key — the class
+ * `design/48-payload-addressing.md` exists to prevent.
+ *
+ * `tests/rsc-media-type-single-source.test.ts` fails if the literal reappears
+ * in executable source outside this file.
+ *
+ * Isomorphic: zero imports, so `adapters/cloudflare.ts` — which Node's native
+ * ESM loader evaluates before Vite's resolver exists — can load it and
+ * interpolate the value into the generated worker. Same precedent as
+ * `shared/rsc-cache-key.ts`.
+ *
+ * See design/19-client-navigation.md, design/25-production-deployments.md
+ * §"`Vary` and the Workers Cache API".
+ */
+/** Media type of a React Flight payload. */
+export declare const RSC_CONTENT_TYPE = "text/x-component";
+/**
+ * Is this request asking for an RSC payload rather than a full document?
+ *
+ * Substring containment, deliberately: `Accept` is a list, and a client may
+ * send `text/x-component;charset=utf-8` or list it alongside other types.
+ * Tightening this to a real media-type parse is a behaviour change that has
+ * to move the adapter's generated `isRsc` in the same commit — see above.
+ */
+export declare function isRscRequest(req: Request): boolean;
+//# sourceMappingURL=rsc-media-type.d.ts.map

package/dist/shared/rsc-media-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rsc-media-type.d.ts","sourceRoot":"","sources":["../../src/shared/rsc-media-type.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAElD"}

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/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) |
 

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,18 @@ 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`
@@ -101,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/more/01-advanced-routing.mdx

@@ -67,7 +67,7 @@ This is useful for CDN-cacheable file-extension routes (e.g. image generation en
 - 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"`
-- `params.ts` codecs use the bare param name (`id`), not the full segment pattern
+- `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`.
 

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

@@ -64,9 +64,9 @@ app/
 
 **Next.js:** `useSearchParams()` hook returns a `URLSearchParams` object.
 
-**timber:** Typed search params via `defineSearchParams` in a `params.ts` file. 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.
+**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/params.ts"
+```ts title="app/products/search-params.ts"
 import { defineSearchParams } from '@timber-js/app/search-params';
 import { z } from 'zod/v4';
 

package/docs/more/50-ai-agent-instructions.mdx

@@ -59,7 +59,7 @@ These are the things you will get wrong if you assume Next.js behavior.
 | Middleware | Single global `middleware.ts` with matchers | Per-segment `middleware.ts` files + global `proxy.ts`. One-arg signature: `middleware(ctx)`. |
 | `notFound()` | `notFound()` from `next/navigation` | `deny(404)` from `@timber-js/app/server`. Sends a real HTTP 404. |
 | `redirect()` | `redirect()` from `next/navigation` | `redirect()` from `@timber-js/app/server`. Same concept, different import. |
-| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas in `params.ts`. |
+| Search params | Untyped `useSearchParams()` | Typed `defineSearchParams()` with Zod schemas, in any module you import. |
 | Auth pattern | In middleware or components | `access.ts` per segment with slot degradation. |
 | Forms | `useFormState` / `useFormStatus` | `createActionClient` + `useActionState` returns a 4-tuple. Forms work without JS. |
 
@@ -71,7 +71,7 @@ These are the things you will get wrong if you assume Next.js behavior.
 | `Link`, `useRouter`, `usePathname`, `useActionState` | `@timber-js/app/client` |
 | `cache`, `CacheHandler` | `@timber-js/app/cache` |
 | `defineSearchParams` | `@timber-js/app/search-params` |
-| `defineSchema`, `defineSegmentParams` | `@timber-js/app/params` |
+| `defineSchema`, `InferCodecType` | `@timber-js/app/params` |
 | Content collection data | `content-collections` |
 | `Metadata` type | `@timber-js/app/server` |
 
@@ -90,7 +90,7 @@ app/                    # Route tree — file-system routing
     access.ts           # Per-segment authorization
     denied.tsx          # Rendered when access.ts denies
     error.tsx           # Error boundary for this segment
-    params.ts           # Search param definitions
+    search-params.ts    # Search param definitions (ordinary module, not a convention)
   schema.ts             # Segment param schemas (from @timber-js/app/params)
 content/                # Content collections (outside route tree)
 timber.config.ts        # Framework configuration
@@ -104,6 +104,8 @@ content-collections.ts  # Collection definitions (optional)
 
 2. **Adding `'use client'` to everything** — components are server components by default. Only add `'use client'` when you need browser APIs, event handlers, or React hooks like `useState`/`useEffect`.
 
+   The exception: `error.tsx`, `global-error.tsx`, and component status files (`404.tsx`, `4xx.tsx`, `503.tsx`, …) **always** need `'use client'`. timber passes them to a client error boundary as a prop, so a server component there breaks every page under that segment. The build rejects it and names the file. MDX status files (`404.mdx`) are exempt.
+
 3. **Using `fetch()` and expecting caching** — timber never patches `fetch`. Wrap data-fetching functions in `cache.data()` from `@timber-js/app/cache` when you want caching.
 
 4. **Creating `loading.tsx` files** — this convention does not exist. Use `<Suspense>` with an explicit fallback where you want streaming.
@@ -114,7 +116,7 @@ content-collections.ts  # Collection definitions (optional)
 
 7. **Putting all middleware in one file** — middleware is per-segment. Place `middleware.ts` at the route level that matches the concern. Use `proxy.ts` for global concerns.
 
-8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in a `params.ts` file with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
+8. **Assuming `useSearchParams()` exists** — use `defineSearchParams()` in any module with Zod schemas, then access via `.get()` (server) or `.useQueryStates()` (client).
 
 ## Quick Patterns