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

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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.186",
+  "version": "0.2.0-alpha.188",
   "description": "Vite-native React framework built for Servers and Serverless Platforms — correct HTTP semantics, real status codes, pages that work without JavaScript",
   "keywords": [
     "cloudflare-workers",
@@ -113,10 +113,6 @@
       "types": "./dist/search-params/index.d.ts",
       "import": "./dist/search-params/index.js"
     },
-    "./segment-params": {
-      "types": "./dist/segment-params/index.d.ts",
-      "import": "./dist/segment-params/index.js"
-    },
     "./params": {
       "types": "./dist/params/index.d.ts",
       "import": "./dist/params/index.js"
@@ -165,6 +161,7 @@
     "@content-collections/mdx": "^0.2.0",
     "@content-collections/vite": "^0.2.0 || ^0.3.0",
     "@mdx-js/rollup": "^3.0.0",
+    "@typescript/native-preview": "^7.0.0-dev.0",
     "@vitejs/plugin-react": "^6.0.0",
     "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
@@ -187,6 +184,9 @@
     "@mdx-js/rollup": {
       "optional": true
     },
+    "@typescript/native-preview": {
+      "optional": true
+    },
     "wrangler": {
       "optional": true
     },
@@ -194,6 +194,9 @@
       "optional": true
     }
   },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2"
+  },
   "engines": {
     "node": ">=22.18.0"
   },

package/src/adapters/cloudflare.ts

@@ -20,6 +20,9 @@ import { adapterBase, generateHeadersFile } from './shared.js';
 // native ESM loader evaluates before Vite's resolver exists. Same precedent as
 // `adapters/shared.ts` importing `../shared/base-path.js`.
 import { RSC_KEY_HEADERS } from '../shared/rsc-cache-key.js';
+// Same reasoning: the media type the origin's own RSC gate matches on, so the
+// two predicates cannot drift apart. See `shared/rsc-media-type.ts`.
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
 
 // ─── Bindings passthrough ─────────────────────────────────────────────────
 // ALS stores the env object per-request so server components and middleware
@@ -486,7 +489,7 @@ ${handlersSpread}  async fetch(request, env, ctx) {
     // This exclusion is load-bearing in the other direction too: the store
     // predicate below treats "Vary: Accept" as honoured *because* of it
     // (see VARY_HONORED). Removing it would make that allowlist unsound.
-    const isRsc = request.headers.get('Accept')?.includes('text/x-component')
+    const isRsc = request.headers.get('Accept')?.includes(${JSON.stringify(RSC_CONTENT_TYPE)})
     const reqCc = request.headers.get('Cache-Control') || ''
     const bypassCache = reqCc.includes('no-cache') || reqCc.includes('max-age=0')
         || request.headers.has('Pragma')

package/src/adapters/compress-module.ts

@@ -7,12 +7,90 @@
 // hand-written string template, any fix to server/compress.ts automatically
 // flows to the production module. See design/18-build-system.md ("entry
 // modules are real TypeScript files, not codegen strings").
+//
+// The transform strips types; it does NOT bundle. The emitted file sits
+// alone in the build output, so any import specifier that survives into it
+// is a module resolution failure at runtime on the deployed server. Shared
+// constants are therefore interpolated here — the same treatment the
+// Cloudflare worker template gives `RSC_KEY_HEADERS` — and anything else
+// that reaches the output as an import is rejected with a build error
+// rather than shipped.
 
 import { transformWithOxc } from 'vite';
 // Vite's ?raw import embeds the file as a string at build time — works
 // in both dev (Vite resolves the TS source) and the published package
 // (the string is inlined into the compiled adapter entry).
 import compressSource from '../server/compress.ts?raw';
+import { RSC_CONTENT_TYPE } from '../shared/rsc-media-type.js';
+
+/**
+ * The one import `server/compress.ts` is allowed to carry, and its inlined
+ * form.
+ *
+ * The binding list is matched exactly rather than as `{…}`. A second binding
+ * added to that import would otherwise be erased along with the statement and
+ * become a `ReferenceError` in the deployed `_compress.mjs` — the failure this
+ * whole module exists to make impossible. Matching exactly means such an
+ * import falls through to the rejection below instead.
+ */
+const INLINED_IMPORTS: ReadonlyArray<{ pattern: RegExp; replacement: string }> = [
+  {
+    pattern:
+      /^import\s*\{\s*RSC_CONTENT_TYPE\s*,?\s*\}\s*from\s*["'][^"']*shared\/rsc-media-type\.js["'];?[ \t]*$/m,
+    replacement: `const RSC_CONTENT_TYPE = ${JSON.stringify(RSC_CONTENT_TYPE)};`,
+  },
+];
+
+/**
+ * Every way a module specifier can reach the emitted file, minus Node
+ * builtins.
+ *
+ * `node:*` is exempt because it resolves on the deployed server exactly as it
+ * does here — `_compress.mjs` already imports `node:zlib` and `node:stream`,
+ * and self-hosted (Node/Bun) is the only place this file runs. Everything
+ * else — relative paths, bare packages — has no resolution target next to a
+ * lone `.mjs` in the build output.
+ *
+ * All three forms are listed rather than the one `server/compress.ts` happens
+ * to use, because a re-export or a lazy `await import()` fails in exactly the
+ * same place and is exactly as invisible until deploy.
+ */
+const MODULE_SPECIFIERS: readonly RegExp[] = [
+  // import … from '…'  /  export … from '…'
+  /^[ \t]*(?:import|export)\b[^\n]*\bfrom\s*["'](?!node:)[^"']+["']/m,
+  // import '…'  (side effect only)
+  /^[ \t]*import\s*["'](?!node:)[^"']+["']/m,
+  // import('…')  (dynamic, literal specifier)
+  /\bimport\s*\(\s*["'](?!node:)[^"']+["']/,
+];
+
+/**
+ * Replace the shared-module imports with their values and reject anything
+ * else that would leave a dangling specifier in `_compress.mjs`.
+ *
+ * Exported separately from `generateCompressModule` so both branches can be
+ * driven with fixtures: the source it normally compiles is fixed, so a test
+ * of the generator alone can only ever exercise whichever branch that source
+ * happens to take today.
+ *
+ * @internal Exported for testing.
+ */
+export function inlineCompressImports(code: string): string {
+  let out = code;
+  for (const { pattern, replacement } of INLINED_IMPORTS) {
+    out = out.replace(pattern, replacement);
+  }
+  const surviving = MODULE_SPECIFIERS.map((pattern) => pattern.exec(out)).find(Boolean);
+  if (surviving) {
+    throw new Error(
+      `[timber] server/compress.ts is emitted as a standalone _compress.mjs (type-stripped, ` +
+        `not bundled), so it cannot import anything at runtime. Found: ${surviving[0].trim()}\n` +
+        `  Either inline the value in adapters/compress-module.ts (see INLINED_IMPORTS) or ` +
+        `keep the dependency out of server/compress.ts.`
+    );
+  }
+  return out;
+}
 
 /**
  * Compile server/compress.ts into a standalone ESM module.
@@ -31,6 +109,6 @@ export async function generateCompressModule(): Promise<string> {
   return (
     '// Generated by @timber-js/app — compiled from server/compress.ts.\n' +
     '// Do not edit — this file is regenerated on each build.\n' +
-    result.code
+    inlineCompressImports(result.code)
   );
 }