@timber-js/app 0.2.0-alpha.196 → 0.2.0-alpha.198

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

@@ -1,6 +1,6 @@
 ---
 title: 'API: TypeScript'
-description: 'Generated route types, $segment modules, typed Link, typed params, and the Routes interface.'
+description: 'Generated route types, $segment module exports, context types, and the Routes interface.'
 slug: 'api-typescript'
 ---
 
@@ -32,95 +32,16 @@ export type AllSegmentParams = { /* union of all route params */ };
 
 Types reference your `app/schema.ts` codecs directly, so they stay in sync automatically.
 
-## `$segment` — Per-Route Type Narrowing
+## `$segment` Module
 
-Each route directory gets a generated `$segment` module (via TypeScript's `rootDirs`). Import `SEGMENT_PATH` for type-safe param access:
-
-```tsx
-// app/products/[id]/page.tsx
-import { SEGMENT_PATH } from './$segment';
-import { getSegmentParams } from '@timber-js/app/server';
-
-export default async function ProductPage() {
-  const { id } = getSegmentParams(SEGMENT_PATH);
-  // id is typed from your schema codec (e.g., number for codec.integer)
-}
-```
-
-### Exports
+Each route directory gets a generated `$segment` module, resolved via TypeScript's `rootDirs` (setup and usage in [Typed Routes](/docs/typed-routes)).
 
 | Export         | Type                | Description                                                   |
 | -------------- | ------------------- | ------------------------------------------------------------- |
 | `ROUTE`        | String literal      | URL route pattern, groups stripped (e.g., `'/products/[id]'`) |
 | `SEGMENT_PATH` | String literal      | Full tree path including groups and slots                     |
 
-### tsconfig.json
-
-Add `rootDirs` so TypeScript can resolve `$segment` imports:
-
-```jsonc
-{
-  "compilerOptions": {
-    "rootDirs": [".", ".timber/types"]
-  }
-}
-```
-
-## Typed `<Link>`
-
-`<Link>` validates `href` against the route map:
-
-```tsx
-import { Link } from '@timber-js/app/client';
-
-<Link href="/about">About</Link>           // ✓
-<Link href="/nonexistent">Bad</Link>        // ✗ TypeScript error
-```
-
-For dynamic routes, pass `segmentParams`:
-
-```tsx
-import { Link } from '@timber-js/app/client';
-
-<Link href="/products/[id]" segmentParams={{ id: 42 }}>
-  Product
-</Link>
-// → <a href="/products/42">Product</a>
-```
-
-## Typed Segment Params
-
-With `SEGMENT_PATH` from `$segment`, param types are narrowed from your `app/schema.ts` codecs:
-
-```tsx
-// app/products/[id]/page.tsx
-import { SEGMENT_PATH } from './$segment';
-import { getSegmentParams } from '@timber-js/app/server';
-
-export default async function ProductPage() {
-  const { id } = getSegmentParams(SEGMENT_PATH);
-  // id: number (from z.coerce.number().int().positive() in schema.ts)
-}
-```
-
-Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — all optional.
-
-## Typed Search Params
-
-Search params are typed by the definition you create and import — there is no convention file:
-
-```ts
-// app/products/search-params.ts — any module you like
-import { defineSearchParams } from '@timber-js/app/search-params';
-import { z } from 'zod/v4';
-
-export const searchParams = defineSearchParams({
-  page: z.coerce.number().default(1),
-  sort: z.enum(['price', 'name']).default('price'),
-});
-
-// In page.tsx — searchParams.get() returns { page: number; sort: 'price' | 'name' }
-```
+`<Link>` `href` validation and `segmentParams`/`searchParams` typing are described in [Typed Routes](/docs/typed-routes); the param and search-param definitions they draw from are in [Typed Params](/docs/typed-params).
 
 ## Context Types
 

package/docs/learn/03-fetching-data.mdx

@@ -76,7 +76,7 @@ export default async function ProductPage() {
 }
 ```
 
-`deny(404)` sends a real HTTP 404 — not a 200 with an error message. Search engines, CDNs, and `curl -f` all see the correct status code.
+`deny(404)` sends a real HTTP 404 — not a 200 with an error message. Search engines, CDNs, and `curl -f` all see the correct status code. Other status codes, status-code files, and error boundaries are covered in [Error Handling](/docs/error-handling).
 
 For typed params (numbers, UUIDs, enums), define codecs in `app/schema.ts`. See [Typed Params](/docs/typed-params).
 

package/docs/learn/{03b-access-control.mdx → 04-access-control.mdx}

@@ -89,15 +89,7 @@ export default async function access() {
 
 Access runs root-to-leaf. If the root gate fails, deeper gates never execute.
 
-## `deny()`
-
-`deny()` produces the correct HTTP status code and renders the matching status file:
-
-```ts
-deny();      // 403 Forbidden (default)
-deny(404);   // 404 Not Found
-deny(401);   // 401 Unauthorized
-```
+`deny()` defaults to `403`; pass a status code (`deny(404)`, `deny(401)`) to change it. How the status code becomes a rendered page is covered in [Error Handling](/docs/error-handling).
 
 ## Slot Degradation
 
@@ -120,11 +112,4 @@ When access denies, that segment's `layout.tsx` never runs — `denied.tsx` rend
 
 ## Middleware vs Access
 
-|               | `middleware.ts`                        | `access.ts`                       |
-| ------------- | -------------------------------------- | --------------------------------- |
-| Runs          | Before rendering                       | Inside React tree                 |
-| Purpose       | Lightweight checks, redirects, headers | Auth, data gating                 |
-| `React.cache` | Not available                          | Active — shares scope with layout |
-| Slots         | N/A                                    | Graceful degradation              |
-
-Use `middleware.ts` for headers, redirects, and cache warming. Use `access.ts` for auth — it has access to `React.cache` and supports slot degradation.
+`access.ts` runs inside the React tree, so it has `React.cache` and supports slot degradation. `middleware.ts` runs before rendering, for headers, redirects, and cache warming. The full comparison is in [Middleware](/docs/middleware).

package/docs/learn/05-the-flush-point.mdx

@@ -0,0 +1,175 @@
+---
+title: 'The Flush Point'
+description: 'When timber commits the HTTP status code, why there is no loading.tsx, and how Early Hints keep it fast.'
+slug: 'the-flush-point'
+# notAI: true
+---
+
+# The Flush Point
+
+The flush point is when the framework sends the first byte of HTML to the browser and commits the HTTP status code. In a traditional PHP website, this happens all at once.
+
+But modern web frameworks, and notably react server components, have embraced a streaming architecture. Allowing you to send content _after_ the flush point.
+
+While this is ultimately incredibly powerful, it brings forth confusion because contextually, code can have different side effects depending on _when_ you call it.
+
+On a next.js app, if I call `notFound()` inside of a `page.tsx` that has a sibling `loading.tsx` – my status code will return `200`. By obfuscating the flush point, we've actually just made developer clarity murky.
+
+So timber works differently. At no point does timber flush early, unless _you_ (the developer), choose to place a `<Suspense>` boundary. Often this will end up being below your `page.tsx` level, so you'll still have access to controlling and sending proper status codes.
+
+## You Might Not Need A `loading.tsx`
+
+Most React frameworks push you towards building page-level skeletons or loading states. Though it's entirely trivial to build out that experience with timber, we nudge you away from that for several reasons.
+
+This is not referring to loading states on things like mutations (like submitting a form) or other actions. This is referring to initial (server) or secondary (client) page loading.
+
+This is how we as frontend engineers make browsing the web a less anxiety-inducing experience.
+
+### Loading States Are an Extra Class of UI to Maintain
+
+You have to design loading states. Decide between spinners and skeletons, and then mimic your UI in the skeleton.
+
+### Loading States Cause Content Layout Shift
+
+Loading states are fixed and content is most often dynamic both in size (think text length) and count (think number of rows). So even if you work incredibly hard to avoid major CLS, you'll invariably end up with CLS somewhere.
+
+### Loading States Are a Flash of UI
+
+Loading states are inherently temporary, so this adds flashes of content. This causes anxiety as the page spasms before finally reaching an undetermined final state. The user is left in a daze wondering if the page is finally ready.
+
+Every possible "finite state" of UI is another that you and the user have to keep in context. You'll be _surprised_ how much simpler a website feels when a page has one major representation, vs several.
+
+### Loading States Hide Prior Context
+
+Go to an old PHP site and click a URL. The _browser_ shows a loading state, but the prior page remains visible. The new page only becomes visible once it is ready. There's little advantage to hiding the past context while the user waits for the new context to load.
+
+### timber Includes a Global Route-Based Loading State
+
+On every route change, timber triggers a global page-level toploader loading state. If you want to add a secondary loading state that dims the prior content, you can easily do so.
+
+### Loading States Break JavaScript Disabled Requests
+
+`curl` a page with a `loading.tsx` and you'll get back a shell, not the content. Though people downsell the cost, it genuinely does hinder both SEO and agentic requests.
+
+Leaning on the web as intended is always better than assuming _all_ consumers have JavaScript enabled. Plus, sticking JavaScript in between your _hot_ rendering path is _inherently_ slower. It's just not necessary when you adopt a comprehensive web architecture like React Server Components.
+
+### Loading States Break Status Codes
+
+Loading states flush before the content is even fetched. This feels _faster_, but you are flushing before you know if the user is authenticated, the data exists, or any other class of issue. By flushing immediately, you are forced to send a 200 and lean on JavaScript-injected meta tags to signify errors.
+
+This breaks the contract of the web for any consumer that isn't a human. Use real status codes, you will gain downstream benefits from doing so.
+
+### Most Loading States Paper Over a Bad Data Architecture
+
+People often use loading states because their database is poorly optimized, or 50ms away from their rendering server, or otherwise. With a well designed data infrastructure, you can often fetch your data plenty fast to render your entire page in < 100ms.
+
+And when you can't, you can stream and flush those rare pages trivially.
+
+### Loading States Still Have Value, but More-So as Opt-In Secondary or Tertiary Content
+
+To add a loading state as a small sub-section of a page is trivial – just wrap your component in `<Suspense>` and you can defer slower, lower priority content.
+
+If you decide you want a full page level loading state, you can wrap your layout or page in `<Suspense>` on a case by case basis. No `loading.tsx` needed.
+
+--------
+
+A `loading.tsx` forces your flush point up ever so slightly, but you give up all the things above. Instead, timber asks you to place `<Suspense>` boundaries yourself – thereby _explicitly_ opting into the flush point.
+
+Now you get a calm, performant website that doesn't have immense content-layout-shift, doesn't hide prior content during loading, and can return proper status codes. The `loading.tsx` seems innocent enough, but its cost both cognitively and architecturally is high.
+
+------
+
+AI below..
+
+## The Problem
+
+Most streaming frameworks send a `200 OK` immediately and figure out the real outcome later:
+
+```
+Request → 200 OK → ... render ... → oh, it's a 404
+```
+
+By the time the server discovers the page doesn't exist, the status code is already sent. The client sees `200`. Search engines see `200`. CDNs cache it as `200`.
+
+This breaks search engines (deleted pages never deindex), CDNs (404s get cached as successes), monitoring (zero errors while users see broken pages), and `curl`/scripts (`curl -f` won't detect the failure).
+
+## timber's Solution
+
+timber holds the response until it knows the real outcome:
+
+```
+Request arrives
+  → Route matched
+  → proxy.ts runs
+  → middleware.ts runs
+  → access.ts runs
+  → React shell renders (onShellReady)
+  → ✓ Status code committed ← flush point
+  → Shell HTML sent to browser
+  → Suspense boundaries stream in
+```
+
+The status code commits when **all three** conditions are met:
+
+1. Middleware completed without returning a response
+2. All access checks passed (or denied with a real status code)
+3. React's `onShellReady` fired — the synchronous shell rendered without error
+
+A missing page returns a real `404`. A failed auth check returns a real `403`. A redirect returns a real `302`. The HTTP layer tells the truth.
+
+## Before and After the Flush
+
+**Before the flush** (blocking):
+
+- `proxy.ts` — global request processing
+- `middleware.ts` — route-level request processing
+- `access.ts` — authorization gates
+- Synchronous component rendering (the shell)
+
+**After the flush** (streaming):
+
+- `<Suspense>` boundaries resolve and stream in
+- Slow data loads complete
+- The page progressively fills in
+
+``` leading="none"
+         ┌─────── flush point
+         │
+         ▼
+├────────┤──────────────────────────┤
+ blocking    streaming
+ (shell)     (suspense boundaries)
+```
+
+Everything before the flush determines the status code. Everything after streams progressively. You control the boundary by choosing what goes inside `<Suspense>` and what doesn't — see [Streaming](/docs/streaming) for how to place those boundaries.
+
+## Pages Work Without JavaScript
+
+Because timber holds the flush until the shell is complete, the browser receives a fully-formed HTML document. Content is visible, links work as standard `<a>` tags, and forms submit as standard POSTs. JavaScript adds client-side navigation, interactive components, and streaming updates — but the page works without it.
+
+This isn't a special mode. It's how timber works by default.
+
+## Early Hints
+
+timber doesn't make you wait for assets while the shell renders. At route-match time — before middleware runs — timber sends `103 Early Hints` with CSS, JS, and font URLs based on the build manifest. The browser starts downloading assets while the server is still working:
+
+```
+103 Early Hints
+Link: </styles/main.css>; rel=preload; as=style
+Link: </chunks/page-abc.js>; rel=modulepreload
+
+... middleware runs, shell renders ...
+
+200 OK
+<html>...
+```
+
+You get the correctness of a held flush with the performance of early resource loading.
+
+## How to Think About It
+
+Primary content — the data that defines whether a page exists, who can see it, and what it contains — should load before the flush. Put it in your components directly.
+
+Secondary content — recommendations, activity feeds, analytics widgets — can load after the flush. Wrap it in `<Suspense>`.
+
+The flush point is the dividing line between "what the page _is_" and "what the page _also shows_."

package/docs/learn/{05-typed-params.mdx → 06-typed-params.mdx}

@@ -52,7 +52,7 @@ Every dynamic segment key must be unique across segment types (dynamic, catch-al
 
 ### Type Narrowing with `$segment`
 
-Each route directory gets a generated `./$segment` virtual module that exports `SEGMENT_PATH` — a string literal typed to the segment's tree path. Import it and pass it to `getSegmentParams()` for exact types:
+Each route directory gets a generated `./$segment` module that exports `SEGMENT_PATH` — a string literal typed to the segment's tree path (how it's generated and the `tsconfig` setup are in [Typed Routes](/docs/typed-routes)). Pass it to `getSegmentParams()` for exact types:
 
 ```tsx title="app/products/[id]/page.tsx" use="schema"
 import { SEGMENT_PATH } from './$segment';

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

@@ -1,12 +1,12 @@
 ---
 title: 'Typed Routes'
-description: 'Build-time route types — <Link> validates href, params are inferred from the file tree.'
+description: 'Build-time route types — <Link> validates href, $segment narrows params to the current route.'
 slug: 'typed-routes'
 ---
 
 # Typed Routes
 
-timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree. Segment params are inferred from directory names. Search params are typed when you define them.
+timber.js generates route types at build time. `<Link>` type-checks `href` against your actual route tree, and every route directory gets a `$segment` module that narrows params to that route. This page covers what the codegen gives you; defining and reading params is covered in [Typed Params](/docs/typed-params).
 
 ## How It Works
 
@@ -53,9 +53,26 @@ Or use an interpolated href directly:
 
 Both forms are type-safe. With the pattern form (`/products/[id]`), `segmentParams` is required and typed. With the interpolated form, `segmentParams` is forbidden.
 
-## Typed Segment Params
+### Search params on `<Link>`
 
-Each route directory gets a generated `$segment` module. Import `SEGMENT_PATH` for type-safe param access:
+Build search params from a `defineSearchParams` 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={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.
+
+## `$segment` and `SEGMENT_PATH`
+
+Each route directory gets a generated `$segment` module. It exports `SEGMENT_PATH`, a string literal typed to that directory's position in the route tree. Passing it to `getSegmentParams()` / `useSegmentParams()` narrows the result to exactly the params that exist at that depth:
 
 ```tsx
 // app/products/[id]/page.tsx
@@ -68,7 +85,9 @@ export default async function ProductPage() {
 }
 ```
 
-Without `SEGMENT_PATH`, params are untyped — all optional strings.
+Without `SEGMENT_PATH`, params are `Partial<AllSegmentParams>` — every param optional.
+
+`$segment` also exports `ROUTE`, the URL pattern with route groups stripped (e.g. `'/products/[id]'`).
 
 ### tsconfig.json
 
@@ -82,51 +101,8 @@ Add `rootDirs` so TypeScript can resolve `$segment` imports:
 }
 ```
 
-## Typed Search Params
-
-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/search-params.ts"
-import { defineSearchParams, withDefault, withUrlKey } from '@timber-js/app/search-params';
-import { parseAsInteger, parseAsStringEnum } from 'nuqs';
-import { z } from 'zod/v4';
-
-export const searchParams = defineSearchParams({
-  page: withDefault(parseAsInteger, 1),
-  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 './search-params';
-
-export default async function ProductsPage() {
-  const { page, q, category, sort } = await searchParams.get();
-  // page: number, q: string | null, category: string | null, sort: 'price-asc' | ...
-}
-```
-
-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={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
 
 Types are generated during `timber dev` (on startup and when routes change) and `timber build`. The generated `.timber/routes.d.ts` is gitignored — it's a build artifact. Run `timber dev` once to get types for your editor.
 
-For the full type definitions and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).
+For the generated type shapes and context types (`RouteContext`, `MiddlewareContext`, `AccessContext`), see the [TypeScript API Reference](/docs/api-typescript).

package/docs/learn/{08-streaming.mdx → 09-streaming.mdx}

@@ -74,9 +74,7 @@ The product loads before the flush — if it doesn't exist, the server sends a r
 
 The rule: if missing content means the page shouldn't exist, don't stream it.
 
-## No `loading.tsx`
-
-There is no `loading.tsx` convention. timber does not insert Suspense boundaries for you. If you want a loading state, you place `<Suspense>` explicitly. This keeps you in control of what streams and what blocks.
+There is no `loading.tsx` convention — timber never inserts Suspense boundaries for you. See [The Flush Point](/docs/the-flush-point) for why.
 
 ## The Layout Suspense Footgun
 
@@ -140,7 +138,3 @@ When `deny()` or `redirect()` fires inside a `<Suspense>` boundary:
 `deferSuspenseFor` extends the window where signals can be promoted.
 
 **The rule:** don't rely on Suspense-wrapped content to control the status code. If content must drive the status code, fetch it outside `<Suspense>`. Signal promotion is a safety net, not a guarantee.
-
-## Early Hints (103)
-
-Before the flush, timber sends 103 Early Hints with CSS, fonts, and JS URLs. These fire at route-match time — before middleware runs — based on the build manifest. The browser starts fetching resources while the server is still working.

package/docs/learn/{10-middleware.mdx → 11-middleware.mdx}

@@ -83,6 +83,7 @@ export default async function middleware(ctx: MiddlewareContext) {
   ctx.segmentParams;    // Route params (already coerced by schema.ts)
   ctx.headers;          // Response headers (writable)
   ctx.requestHeaders;   // Request headers (injectable)
+  ctx.nonce;            // Per-request CSP nonce (see Security → Content Security Policy)
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timber-js/app",
-  "version": "0.2.0-alpha.196",
+  "version": "0.2.0-alpha.198",
   "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",
@@ -165,8 +165,8 @@
     "@vitejs/plugin-react": "^6.1.0",
     "@vitejs/plugin-rsc": ">=0.5.28",
     "nuqs": "^2.0.0",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "react": "19.3.0-canary-f789f203-20260825",
+    "react-dom": "19.3.0-canary-f789f203-20260825",
     "satteri": "^0.9.5",
     "vite": "8.2.1",
     "vite-plugin-satteri": "^0.2.15",

package/src/adapters/nitro.ts

@@ -5,23 +5,23 @@
 // compression, graceful shutdown, static file serving, and platform quirks.
 // See design/11-platform.md and design/25-production-deployments.md.
 
-import { writeFile, readFile, cp, glob } from 'node:fs/promises';
-import { join, dirname, basename } from 'node:path';
-import type { TimberPlatformAdapter, TimberConfig } from './types.ts';
-import { generateCompressModule } from './compress-module.ts';
-import { adapterBase, IMMUTABLE_CACHE, generateHeadersFile } from './shared.ts';
+import { cp, glob, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
 import {
-  runSharedBuildSteps,
   buildStaticDirectoryOutput,
   findUnhashedStaticFiles,
+  runSharedBuildSteps,
   writeHeadersFile,
 } from './build-output-helper.ts';
-import { PRESET_CONFIGS, LOCALLY_PREVIEWABLE, type NitroPreset } from './nitro-presets.ts';
+import { generateCompressModule } from './compress-module.ts';
+import { LOCALLY_PREVIEWABLE, PRESET_CONFIGS, type NitroPreset } from './nitro-presets.ts';
 import {
   generatePreviewScript,
   generateSendResponseModule,
   spawnNitroPreview,
 } from './nitro-preview.ts';
+import { IMMUTABLE_CACHE } from './shared.ts';
+import type { TimberConfig, TimberPlatformAdapter } from './types.ts';
 
 // NitroPreset is part of the public adapter API (NitroAdapterOptions.preset),
 // so it stays importable from this module.

package/src/cache/singleflight.ts

@@ -18,6 +18,8 @@ export interface SingleflightOptions {
 
 export interface Singleflight {
   do<T>(key: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+  /** Return the in-flight promise for a key, or undefined if none. */
+  get(key: string): Promise<unknown> | undefined;
 }
 
 /**
@@ -80,5 +82,8 @@ export function createSingleflight(opts?: SingleflightOptions): Singleflight {
       inflight.set(key, tracked);
       return tracked as Promise<T>;
     },
+    get(key: string): Promise<unknown> | undefined {
+      return inflight.get(key);
+    },
   };
 }