@bractjs/bractjs 0.1.28 → 0.2.0

package/README.md

@@ -11,7 +11,7 @@
 - [Bun](https://bun.sh) ≥ 1.1 — no Node.js support
 - React 19 (peer dependency)
 
-This README is a **step-by-step guide to every function and feature** BractJS exports. Each section is self-contained and ordered from "first app" to "advanced". Every symbol shown here is a real export from `@bractjs/bractjs` (see [src/index.ts](src/index.ts)).
+This README is a **step-by-step guide to every function and feature** BractJS exports. Each section is self-contained and ordered from "first app" to "advanced". Every symbol shown here is a real export from `@bractjs/bractjs` (see [packages/core/src/index.ts](packages/core/src/index.ts)).
 
 ---
 
@@ -154,13 +154,17 @@ Drop a file in `app/routes/`; it becomes a route. BractJS scans at startup and b
 | `routes/about.tsx` | `/about` |
 | `routes/blog/_index.tsx` | `/blog` |
 | `routes/blog/[id].tsx` | `/blog/:id` |
+| `routes/users/[[id]].tsx` | `/users` **and** `/users/:id` (optional) |
 | `routes/docs/[...slug].tsx` | `/docs/*` (catch-all) |
 | `routes/blog/layout.tsx` | wraps all `/blog/*` routes |
+| `routes/(marketing)/about.tsx` | `/about` (group adds no URL segment) |
 
 - `[param]` → a dynamic segment, read via `useParams()` / `params` arg.
+- `[[param]]` → an **optional** dynamic segment: the route matches whether the segment is present or not (when absent, `params.param` is simply unset).
 - `[...name]` → a catch-all; the rest of the path lands in `params.name`.
 - `layout.tsx` in any directory wraps every route under it (layouts nest: `root → blog/layout → blog/[id]`).
-- Match priority per segment: **static > dynamic > catch-all**.
+- `(group)/` → a **route group**: the folder organizes files and contributes its `layout.tsx`, but adds **no** URL segment. Use it to give a set of routes a shared layout without a shared path prefix.
+- Match priority per segment: **static > dynamic > optional > catch-all**.
 
 No registration step — the file IS the route.
 
@@ -171,7 +175,7 @@ No registration step — the file IS the route.
 Every file in `app/routes/` (and `root.tsx`/`layout.tsx`) may export any combination of these. Import the arg types from the package.
 
 ```tsx
-import type { LoaderArgs, ActionArgs, MetaArgs } from "@bractjs/bractjs";
+import type { LoaderArgs, ActionArgs, MetaArgs, HeadersArgs } from "@bractjs/bractjs";
 import { redirect, json, HttpError } from "@bractjs/bractjs";
 
 // 1) loader — runs on every GET. Return value → useLoaderData().
@@ -242,7 +246,40 @@ export function Fallback() {
   return <p>Loading dashboard…</p>;             // SSR'd in the component's place
 }
 
-// 9) default — the page component (required for a renderable route).
+// 9) headers — set response headers (Cache-Control / ETag / Vary / CDN hints)
+//    for this route's document AND /_data responses. Runs root → layout →
+//    route; innermost wins per key, and you receive the merged parentHeaders.
+export function headers({ loaderData, parentHeaders }: HeadersArgs<LoaderData>) {
+  return { "Cache-Control": "public, max-age=300, s-maxage=3600" };
+}
+
+// 10) middleware — nested, server-side. Runs root → layout → route BEFORE
+//     beforeLoad/action/loaders, with a shared mutable `context`. Return a
+//     Response to short-circuit (a cleaner per-route alternative to beforeLoad,
+//     and to a single global pipeline). Protects the document and /_data.
+export const middleware = [
+  async (ctx, next) => {
+    if (!ctx.context.user) return redirect("/login");
+    ctx.context.startedAt = Date.now();         // visible to loaders
+    return next();
+  },
+];
+
+// 11) clientLoader / clientAction — RR7-style browser-side data. clientLoader
+//     runs on navigation and its result becomes useLoaderData(); call
+//     serverLoader() for this route's server data. Set clientLoader.hydrate =
+//     true to also run on the first hydration of an SSR'd document.
+export async function clientLoader({ serverLoader }) {
+  const server = await serverLoader();          // the normal /_data route slice
+  return { ...server, fetchedAt: Date.now() };
+}
+// clientLoader.hydrate = true;                  // opt into running on hydration
+export async function clientAction({ formData, serverAction }) {
+  // optimistic local work, then defer to the server action:
+  return serverAction();
+}
+
+// 12) default — the page component (required for a renderable route).
 export default function BlogPost() {
   const { post } = useLoaderData<LoaderData>();
   return <article><h1>{post.title}</h1></article>;
@@ -252,9 +289,10 @@ export default function BlogPost() {
 **Execution order for a request:**
 
 ```
-searchSchema → beforeLoad → (action, if mutating method) → loaders (root + layouts + route, in parallel) → render
+global pipeline → searchSchema → route middleware (root → layout → route) → beforeLoad → (action, if mutating method) → loaders (root + layouts + route, in parallel) → render
 ```
 
+- **Route middleware** wraps everything after search validation: it runs in chain order with a shared `context`, can short-circuit with a `Response`, and (being outermost-first) can also post-process the final response. It runs inside the app-wide `pipeline` (§14).
 - **Loaders run concurrently** (root, every layout, and the route loader all in one `Promise.all`).
 - A loader that throws an `HttpError`/redirect `Response` is intentional control flow. Any *other* thrown error is caught, sanitized (generic message in production, full message+stack only when `NODE_ENV=development`), and rendered via the nearest `ErrorBoundary`.
 
@@ -431,6 +469,19 @@ const { id } = useParams<{ id: string }>();     // or a hand-written shape
 ```
 > The pattern is supplied by the caller because the framework can't infer the active route at the type level (React Router's `useParams` works the same way).
 
+### `useMatches()` → `RouteMatch[]`
+The matched route chain, **outermost → innermost** (root, layouts, then the leaf route). Each entry is `{ id, pathname, params, data, handle }`, where `handle` is that module's static `handle` export. Ideal for breadcrumbs and conditional chrome without threading props through every layout. SSR-safe; updates on soft navigation and revalidation.
+```tsx
+// routes/blog/[id].tsx
+export const handle = { breadcrumb: "Post" };
+
+// a layout
+const crumbs = useMatches()
+  .filter((m) => m.handle?.breadcrumb)
+  .map((m) => m.handle!.breadcrumb as string);
+```
+> `handle` travels in the SSR bootstrap and the `/_data` payload, so it must be JSON-serializable (same constraint as loader data).
+
 ### `useLocation()` → `{ pathname, search, hash, state, key }`
 The current location — reactive on the client, request-derived during SSR (`hash` is always `""` there). `key` is the history entry's identity (what scroll restoration uses); `state` is whatever you passed via `navigate(to, { state })`.
 ```ts
@@ -659,12 +710,17 @@ export const listUsers = route("GET", "/api/users", async () => {
 export const createUser = route("POST", "/api/users", async (input: { name: string }) => {
   return db.users.create(input);
 });
+
+// Public, credential-free endpoint (e.g. a webhook): opt out of CSRF.
+export const webhook = route("POST", "/api/webhook", handleWebhook, { csrf: false });
 ```
 
 - `GET`/`DELETE`: no body parsed. `POST`/`PUT`/`PATCH`: JSON or form body parsed into `input`.
-- Bodies are capped at 1 MiB. Errors return a generic 500 in production (full message in dev).
+- Bodies are capped at 1 MiB. JSON bodies carrying prototype-pollution keys (`__proto__`/`constructor`/`prototype`) are rejected (400). Errors return a generic 500 in production (full message in dev).
 - Handlers also receive the raw `Request` as the 2nd arg.
 - `:param` segments match any non-empty value; **read and validate params from `request.url` yourself** (they aren't injected into `input`).
+- **CSRF — on by default for mutating methods** (`POST`/`PUT`/`PATCH`/`DELETE`): the request must prove same-origin (via `Sec-Fetch-Site`, the `X-BractJS-Action` header `createClient` sends automatically, or a matching `Origin`), exactly like server actions. Cross-site requests get `403`. Pass `{ csrf: false }` **only** for endpoints that don't trust ambient credentials (session cookies / Basic auth) and are meant to be called cross-site (webhooks, token-authenticated or public APIs).
+- Global `pipeline` middleware (`cors`, `csp`, `authGuard`, custom) applies to `/api` responses too — see §14.
 
 ### Call them with `createClient<AppApiRoutes>()`
 
@@ -726,7 +782,7 @@ If you prefer to keep calling `validate()` and catching: `isValidationResponse(e
 
 ## 14. Middleware
 
-Middleware runs **before routing** on the module-level `pipeline` singleton. Each middleware gets `(ctx, next)` and returns a `Response`. `ctx.context` is threaded into every loader/action.
+The module-level `pipeline` singleton wraps the **entire** request — every response flows through it, including typed `/api` routes, server actions (`/_action`, `/_stream`), the image endpoint (`/_image`), static assets, and SSR documents. So `cors()`, `csp()`, `authGuard()`, a rate limiter, or your own logging applies uniformly, not just to page renders. Each middleware gets `(ctx, next)` and returns a `Response`; `ctx.context` is threaded into every loader/action and into nested route middleware.
 
 ```ts
 import { pipeline, requestLogger, cors, authGuard, csp } from "@bractjs/bractjs";
@@ -768,7 +824,7 @@ pipeline.use(csp({
 ```
 Read the nonce inside a component/middleware with `getCspNonce(context)` (key: `CSP_NONCE_KEY`) to nonce your own inline scripts.
 
-`script-src` is always nonce-based (`'nonce-…' 'strict-dynamic'`), so injected `<script>` cannot execute. The default `style-src` allows `'unsafe-inline'` for ergonomics (React inline styles, CSS-in-JS); this leaves inline-style injection possible. Pass `strict: true` (or override `style-src` with a nonce/hash) if your app serves all styles from same-origin stylesheets.
+`script-src` is always nonce-based (`'nonce-…' 'strict-dynamic'`), so injected `<script>` cannot execute. Note that with `'strict-dynamic'`, supporting browsers **ignore** the `'self'`/host expressions in `script-src` — trust flows solely through the nonce and the scripts it loads (the `'self'` is kept only as a fallback for older browsers). The default policy also sets `form-action 'self'` (a `<form>` can only submit same-origin), `base-uri 'self'`, `frame-ancestors 'self'`, and `object-src 'none'`. The default `style-src` allows `'unsafe-inline'` for ergonomics (React inline styles, CSS-in-JS); this leaves inline-style injection possible. Pass `strict: true` (or override `style-src` with a nonce/hash) if your app serves all styles from same-origin stylesheets.
 
 ### Custom middleware
 
@@ -786,6 +842,27 @@ pipeline.use(trace);
 
 You can also construct an isolated `new MiddlewarePipeline()` and `.run(ctx, handler)` it yourself (used internally and in tests).
 
+### Nested route middleware
+
+The global `pipeline` is app-wide. For middleware scoped to a branch of the route tree, export `middleware` from a route, `layout.tsx`, or `root.tsx` — a single function or an array. It runs **inside** the global pipeline, in chain order (root → layout → route), before `beforeLoad`/action/loaders, sharing the same mutable `context`. Return a `Response` to short-circuit; because the chain is outermost-first, an ancestor can also post-process the response.
+
+```ts
+// routes/admin/layout.tsx — gates every /admin/* route
+import type { RouteMiddlewareFunction } from "@bractjs/bractjs";
+import { redirect } from "@bractjs/bractjs";
+
+const requireAdmin: RouteMiddlewareFunction = async (ctx, next) => {
+  if (!(ctx.context.user as { admin?: boolean } | undefined)?.admin) {
+    return redirect("/login");
+  }
+  return next();                 // continue to child layouts/route + loaders
+};
+
+export const middleware = [requireAdmin];
+```
+
+It protects the **document and the `/_data` soft-nav endpoint** alike, so it's a safe place for auth — same guarantee as `beforeLoad`. Prefer route middleware over `beforeLoad` when you want composition (multiple concerns, shared across a folder) or response post-processing; `beforeLoad` remains the lighter single-gate option.
+
 ---
 
 ## 15. Sessions
@@ -1169,7 +1246,7 @@ bun build --compile app/server.ts \               # D — single binary
 
 The codegen functions are exported: `writeModuleRegistries(appDir)`, `writeManifestModule(appDir, buildDir)`, and the lower-level `generateRouteRegistry` / `generateActionRegistry` / `generateManifestModule`.
 
-> **Contributor note — keep the binary working:** anything on the server request/startup path must avoid runtime `Bun.Glob`/computed-path `import()`, must fall back from `realpath()` to `Bun.file().exists()` for embedded assets, and must preserve every consumed export when projecting route modules. Two tests enforce this: `src/__tests__/compile-safety.test.ts` (fast static scan) and `src/__tests__/compile-smoke.test.ts` (compiles and boots a real binary).
+> **Contributor note — keep the binary working:** anything on the server request/startup path must avoid runtime `Bun.Glob`/computed-path `import()`, must fall back from `realpath()` to `Bun.file().exists()` for embedded assets, and must preserve every consumed export when projecting route modules. Two tests enforce this: `packages/core/src/__tests__/compile-safety.test.ts` (fast static scan) and `packages/core/src/__tests__/compile-smoke.test.ts` (compiles and boots a real binary).
 
 ---
 
@@ -1245,6 +1322,7 @@ export default defineConfig({ port: 3000, clientEnv: ["PUBLIC_API_URL"] });
 | `publicDir` | `string` | `"./public"` | Static assets (served no-cache) |
 | `buildDir` | `string` | `"./build"` | Build output |
 | `imageCacheDir` | `string` | `".bract-image-cache"` | Optimized-image disk cache |
+| `maxRequestBodySize` | `number` | `16777216` (16 MiB) | Hard ceiling on any request body, enforced by the Bun adapter (§27) |
 | `sourcemap` | `string` | `"external"` | `"none" \| "linked" \| "inline" \| "external"` |
 | `minify` | `boolean` | `true` | Minify client bundles |
 | `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
@@ -1261,9 +1339,9 @@ export default defineConfig({ port: 3000, clientEnv: ["PUBLIC_API_URL"] });
 
 ## 26. Full export index
 
-Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
+Everything importable from `@bractjs/bractjs` ([packages/core/src/index.ts](packages/core/src/index.ts)):
 
-**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `safeValidate`, `isValidationResponse`, `readValidationError`, `validateSearch`, `searchParamsToObject`, `formText`, `formValues`, `defineActions`, `BunAdapter`, `defineLifecycle`, `renderSpaShell`
+**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `safeValidate`, `isValidationResponse`, `readValidationError`, `validateSearch`, `searchParamsToObject`, `hasForbiddenKey`, `nullProtoFromEntries`, `formText`, `formValues`, `defineActions`, `BunAdapter`, `defineLifecycle`, `renderSpaShell`
 
 **Errors:** `BractJSError`, `HttpError`, `isRedirect`, `isHttpError`, `isBractJSError`
 
@@ -1271,13 +1349,13 @@ Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
 
 **Context:** `BractJSContext`, `BractJSProvider`, `useBractJSContext`
 
-**Middleware:** `pipeline`, `MiddlewarePipeline`, `requestLogger`, `cors`, `authGuard`, `csp`, `getCspNonce`, `CSP_NONCE_KEY`
+**Middleware:** `pipeline`, `MiddlewarePipeline`, `runRouteMiddleware`, `collectRouteMiddleware`, `requestLogger`, `cors`, `authGuard`, `csp`, `getCspNonce`, `CSP_NONCE_KEY`
 
 **Sessions:** `createCookieSession`
 
 **Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`, `ScrollRestoration`
 
-**Hooks:** `useLoaderData`, `useActionData`, `useLocation`, `useParams`, `useNavigation`, `useNavigate`, `useFetcher`, `useFetchers`, `useRevalidator`, `useSearch`, `useSetSearch`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
+**Hooks:** `useLoaderData`, `useActionData`, `useLocation`, `useParams`, `useMatches`, `useNavigation`, `useNavigate`, `useFetcher`, `useFetchers`, `useRevalidator`, `useSearch`, `useSetSearch`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
 
 **Search serialization:** `serializeSearch`
 
@@ -1293,7 +1371,7 @@ Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
 
 **Adapters:** `createCloudflareAdapter`, `makeCloudflareHandler`
 
-**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `RouterLocation`, `ShouldRevalidateArgs`, `ShouldRevalidateFunction`, `BractJSConfig`, `RenderOptions`, `ServerManifest`, `ContextFactory`, `ApiRouteDefinition`, `AppApiRoutes`, `FieldErrors`, `ValidationError`, `BractAdapter`, `LifecycleHooks`, `MiddlewareFn`, `MiddlewareContext`, `CorsOptions`, `AuthGuardOptions`, `CspOptions`, `SessionStorageLike`, `SessionLike`, `Session`, `SessionStorage`, `SessionData`, `CookieSessionOptions`, `CommitOptions`, `ImageProps`, `ImageFormat`, `ImageFit`, `SearchParamsResult`, `SetSearchFn`, `SetSearchOptions`, `SearchOutputFor`, `InferSchemaOutput`, `LoaderData`, `ActionData`, `SafeValidateResult`, `FetcherResult`, `FetcherEntry`, `FetcherState`, `FetcherFormProps`, `UseFetcherOptions`, `Revalidator`, `ScrollRestorationProps`, `PrerenderOptions`, `PrerenderResult`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
+**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `RouterLocation`, `ShouldRevalidateArgs`, `ShouldRevalidateFunction`, `BractJSConfig`, `RenderOptions`, `ServerManifest`, `ContextFactory`, `ApiRouteDefinition`, `ApiRouteOptions`, `AppApiRoutes`, `FieldErrors`, `ValidationError`, `BractAdapter`, `LifecycleHooks`, `MiddlewareFn`, `MiddlewareContext`, `CorsOptions`, `AuthGuardOptions`, `CspOptions`, `SessionStorageLike`, `SessionLike`, `Session`, `SessionStorage`, `SessionData`, `CookieSessionOptions`, `CommitOptions`, `ImageProps`, `ImageFormat`, `ImageFit`, `SearchParamsResult`, `SetSearchFn`, `SetSearchOptions`, `SearchOutputFor`, `InferSchemaOutput`, `LoaderData`, `ActionData`, `SafeValidateResult`, `FetcherResult`, `FetcherEntry`, `FetcherState`, `FetcherFormProps`, `UseFetcherOptions`, `Revalidator`, `ScrollRestorationProps`, `PrerenderOptions`, `PrerenderResult`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
 
 ---
 
@@ -1303,10 +1381,13 @@ BractJS ships secure defaults, but a few behaviors are worth understanding so yo
 
 - **What `"use server"` publishes.** Every exported **function** of a `"use server"` module becomes an unauthenticated RPC endpoint reachable via `POST /_action` and `GET /_stream`. In files under `routes/`, framework exports (`loader`, `action`, `default`, `meta`, `beforeLoad`, `context`, `ErrorBoundary`, `Fallback`, `config`, `searchSchema`, `ssr`) are **not** registered as actions — but any *other* exported function is. Treat each exported action as a public endpoint: **do your own authorization inside the function body** (read the session, check the user). The CSRF gate only proves the call is same-origin; it does not authenticate the user.
 - **`/_stream` calls actions with no arguments.** A streaming action invoked over `GET /_stream` receives no caller input. It must be safe to call with none and must authorize itself.
-- **CORS + credentials.** Listing an origin in `cors({ origin: [...], credentials: true })` fully trusts that origin for credentialed cross-origin reads. Only list origins you control. `credentials:true` with `origin:"*"` is refused at setup. Never add `X-BractJS-Action` to `Access-Control-Allow-Headers` — it is the CSRF gate.
-- **Error messages.** In production, loader/action errors are surfaced to the client as a generic message; the real message + stack appear only in dev (`NODE_ENV=development`). For user-facing structured errors throw an `HttpError` (its message *is* shown) — never put secrets in a raw `Error.message`.
+- **Typed `/api` routes are CSRF-protected by default.** Mutating routes (`POST`/`PUT`/`PATCH`/`DELETE`) require a same-origin proof just like server actions; cross-site requests get `403`. Opt out with `route(..., { csrf: false })` **only** for endpoints that don't trust ambient credentials (webhooks, token-authenticated/public APIs). As with actions, the CSRF gate is not authentication — authorize inside the handler.
+- **Global middleware covers every endpoint.** Anything attached to `pipeline.use(...)` — `cors()`, `csp()`, `authGuard()`, a rate limiter, custom logging — runs for typed `/api` routes, `/_action`, `/_stream`, `/_image`, static assets, and SSR documents alike. (This was previously SSR-only; a cross-cutting guard you register globally now actually applies to your API surface.)
+- **CORS + credentials.** Listing an origin in `cors({ origin: [...], credentials: true })` fully trusts that origin for credentialed cross-origin reads. Only list origins you control. `credentials:true` with `origin:"*"` is refused at setup. **Never add `X-BractJS-Action` to `Access-Control-Allow-Headers`** — it is part of the CSRF gate; the built-in `cors()` deliberately omits it. If you write your own CORS layer and expose that header cross-origin, you defeat CSRF on both actions and `/api`; add a cryptographic double-submit token if you must. The header-based gate also assumes browsers send `Sec-Fetch-Site` — behind a proxy that strips it, rely on same-origin `Origin` (which `cors()` does not weaken).
+- **Error messages.** In production, loader/action/api errors are surfaced to the client as a generic message; the real message + stack appear only in dev (`NODE_ENV=development`). For user-facing structured errors throw an `HttpError` (its message *is* shown) — never put secrets in a raw `Error.message`.
 - **CSP `style-src`.** The opt-in `csp()` middleware nonces all scripts, but its default `style-src` includes `'unsafe-inline'` for ergonomics. Pass `csp({ strict: true })` (or override `style-src` with a nonce/hash) if you want to block inline-style injection.
-- **Already handled for you:** path traversal + symlink escape on `/public` and `/_image`, open-redirect neutralization (`redirect()` requires `{ allowExternal: true }` to go off-origin), XSS-safe SSR data island (`safeStringify`), prototype-pollution rejection on action JSON bodies, request body-size caps, signed/constant-time-verified cookie sessions, and CSRF via layered `Sec-Fetch-Site` + custom-header + `Origin` checks.
+- **Request body size.** Beyond the per-handler caps (1 MiB JSON for actions/api, 10 MiB route forms), the Bun adapter enforces a hard `maxRequestBodySize` ceiling (default 16 MiB) so no path can stream an unbounded body into memory. Raise it via the `maxRequestBodySize` config for a dedicated large-upload endpoint.
+- **Already handled for you:** path traversal + symlink escape on `/public` and `/_image`, open-redirect neutralization (`redirect()` requires `{ allowExternal: true }` to go off-origin), XSS-safe SSR data island (`safeStringify`), prototype-pollution rejection on action **and** `/api` JSON bodies plus null-prototype objects for form/search inputs, request body-size caps + global backstop, signed/constant-time-verified cookie sessions, CSP defaults (`script-src` nonce + `strict-dynamic`, `form-action`/`base-uri`/`frame-ancestors` `'self'`, `object-src 'none'`), and CSRF via layered `Sec-Fetch-Site` + custom-header + `Origin` checks across actions, `/_stream`, route mutations, and `/api`.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.28",
+  "version": "0.2.0",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",
@@ -42,11 +42,6 @@
       "default": "./src/index.ts"
     }
   },
-  "scripts": {
-    "dev": "bun run src/dev/server.ts",
-    "build": "bun run src/build/bundler.ts",
-    "test": "bun test"
-  },
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19"
@@ -57,5 +52,11 @@
     "@types/react-dom": "^19",
     "react": "^19",
     "react-dom": "^19"
+  },
+  "scripts": {
+    "dev": "bun run src/dev/server.ts",
+    "build": "bun run src/build/bundler.ts",
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
   }
-}
+}

package/src/__tests__/fixtures/app/routes/features-demo.tsx

@@ -0,0 +1,28 @@
+// Fixture exercising the Phase 1/2/4 route exports end-to-end:
+//   - `headers`  → Cache-Control on the document + /_data response
+//   - `handle`   → surfaced via useMatches() (asserted from the payload)
+//   - `middleware` → sets context (read by the loader) and stamps a header
+import type { RouteMiddlewareFunction, HeadersArgs } from "../../../../shared/route-types.ts";
+
+const setUser: RouteMiddlewareFunction = async (ctx, next) => {
+  ctx.context.demoUser = "alice";
+  const res = await next();
+  res.headers.set("X-Demo-Mw", "1");
+  return res;
+};
+
+export const middleware = [setUser];
+
+export const handle = { breadcrumb: "Features" };
+
+export function loader({ context }: { context: Record<string, unknown> }) {
+  return { user: context.demoUser ?? null };
+}
+
+export function headers(_args: HeadersArgs) {
+  return { "Cache-Control": "public, max-age=120" };
+}
+
+export default function FeaturesDemo() {
+  return <p>features</p>;
+}

package/src/__tests__/headers.test.ts

@@ -0,0 +1,111 @@
+import { test, expect, describe } from "bun:test";
+import { resolveHeaders, applyRouteHeaders } from "../server/headers.ts";
+import type { LayoutChain } from "../server/layout.ts";
+import type { LoaderResults } from "../server/loader.ts";
+import type { HeadersFunction } from "../shared/route-types.ts";
+
+const params = {};
+const req = new Request("http://localhost/");
+
+function chain(parts: {
+  root?: HeadersFunction;
+  layouts?: (HeadersFunction | undefined)[];
+  route?: HeadersFunction;
+}): LayoutChain {
+  return {
+    root: parts.root ? { headers: parts.root } : {},
+    layouts: (parts.layouts ?? []).map((h) => (h ? { headers: h } : {})),
+    route: parts.route ? { headers: parts.route } : {},
+  };
+}
+
+function results(over: Partial<LoaderResults> = {}): LoaderResults {
+  return { root: null, layouts: [], route: null, ...over };
+}
+
+describe("resolveHeaders", () => {
+  test("returns null when no module exports headers", () => {
+    expect(resolveHeaders(chain({}), results(), params, req)).toBeNull();
+  });
+
+  test("collects a single route's headers", () => {
+    const merged = resolveHeaders(
+      chain({ route: () => ({ "Cache-Control": "max-age=60" }) }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+  });
+
+  test("innermost route wins per key (route over root)", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0", Vary: "Cookie" }),
+        route: () => ({ "Cache-Control": "max-age=300" }),
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=300");
+    // Root-only key survives.
+    expect(merged?.get("Vary")).toBe("Cookie");
+  });
+
+  test("parentHeaders carries accumulated values to inner links", () => {
+    let seen: string | null = "unset";
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "X-From-Root": "1" }),
+        route: ({ parentHeaders }) => {
+          seen = parentHeaders.get("X-From-Root");
+          return {};
+        },
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(seen).toBe("1");
+    expect(merged?.get("X-From-Root")).toBe("1");
+  });
+
+  test("passes the matching loaderData slice to each link", () => {
+    const merged = resolveHeaders(
+      chain({ route: ({ loaderData }) => ({ ETag: String((loaderData as { etag: string }).etag) }) }),
+      results({ route: { etag: "abc" } }),
+      params,
+      req,
+    );
+    expect(merged?.get("ETag")).toBe("abc");
+  });
+
+  test("layout headers merge between root and route", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0" }),
+        layouts: [() => ({ "Cache-Control": "max-age=10", Vary: "Accept" })],
+        route: () => ({ "Cache-Control": "max-age=60" }),
+      }),
+      results({ layouts: [null] }),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+    expect(merged?.get("Vary")).toBe("Accept");
+  });
+});
+
+describe("applyRouteHeaders", () => {
+  test("overrides same-key defaults and is a no-op for null", () => {
+    const base = new Headers({ "Cache-Control": "no-store", "X-Base": "1" });
+    applyRouteHeaders(base, new Headers({ "Cache-Control": "max-age=60" }));
+    expect(base.get("Cache-Control")).toBe("max-age=60");
+    expect(base.get("X-Base")).toBe("1");
+
+    const base2 = new Headers({ "X-Base": "1" });
+    applyRouteHeaders(base2, null);
+    expect(base2.get("X-Base")).toBe("1");
+  });
+});

package/src/__tests__/integration.test.ts

@@ -182,3 +182,37 @@ test("/_data of a beforeLoad-gated route is blocked and never leaks loader data"
   const body = await res.text();
   expect(body).not.toContain("TOP-SECRET-LOADER-DATA");
 });
+
+// ── Route headers / useMatches / nested middleware (Phases 1, 2, 4) ──────────
+
+test("route `headers` export sets Cache-Control on the document response", async () => {
+  const res = await fetch(`${BASE}/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  // Baseline hardening headers still present (not clobbered).
+  expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+});
+
+test("route `headers` export also applies to the /_data response", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  expect(res.headers.get("content-type")).toContain("application/json");
+});
+
+test("nested middleware runs (sets context read by the loader, stamps a header)", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.headers.get("X-Demo-Mw")).toBe("1");
+  const data = (await res.json()) as { route?: { user?: string } };
+  // The loader saw the context value the middleware set.
+  expect(data.route?.user).toBe("alice");
+});
+
+test("/_data payload carries the matched chain (useMatches) with handle", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  const data = (await res.json()) as { matches?: Array<{ id: string; handle?: { breadcrumb?: string } }> };
+  expect(Array.isArray(data.matches)).toBe(true);
+  // Leaf route carries its handle export.
+  const leaf = data.matches!.at(-1)!;
+  expect(leaf.handle?.breadcrumb).toBe("Features");
+});

package/src/__tests__/layout-registry.test.ts

@@ -58,13 +58,17 @@ describe("resolveLayoutChainFromRegistry", () => {
     expect(r.layoutFiles).toEqual([]);
   });
 
-  test("matches sibling-dir layouts only when route is deeper", () => {
-    // urlPattern "blog" → layoutDirs returns [] (no ancestor)
+  test("wraps a folder index in that folder's layout", () => {
+    // routes/blog/_index.tsx (URL /blog) lives inside routes/blog/, so the
+    // sibling routes/blog/layout.tsx wraps it — matching Remix/RR/Next, where
+    // an index is nested under its directory's layout. Layout dirs are derived
+    // from the FILE path, so the `_index` → `blog` urlPattern collapse no
+    // longer hides the ancestor directory.
     const r = resolveLayoutChainFromRegistry(
       { filePath: "routes/blog/_index.tsx", urlPattern: "blog", segments: ["blog"] },
       registry,
     );
-    expect(r.layoutFiles).toEqual(["root.tsx"]);
+    expect(r.layoutFiles).toEqual(["root.tsx", "routes/blog/layout.tsx"]);
   });
 });
 

package/src/__tests__/matcher.test.ts

@@ -67,3 +67,32 @@ describe("matchRoute", () => {
     expect(r2?.params.id).toBe("123");
   });
 });
+
+describe("optional segments [[id]]", () => {
+  test("matches with the segment present (binds the param)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users/42", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({ id: "42" });
+  });
+
+  test("matches with the segment absent (param unset)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({});
+  });
+
+  test("static sibling still wins over the optional param", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/me")]);
+    const r = matchRoute("/users/me", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/me");
+  });
+
+  test("does not over-consume — extra segment falls through to catch-all", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/[...rest]")]);
+    const r = matchRoute("/users/1/2", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/[...rest]");
+    expect(r?.params.rest).toBe("1/2");
+  });
+});

package/src/__tests__/module-registry.test.ts

@@ -18,9 +18,8 @@ beforeAll(async () => {
   await writeFile(join(TMP, "root.tsx"), `export default function Root() { return null; }\n`);
   await writeFile(join(TMP, "routes", "_index.tsx"), `export default function Home() { return null; }\n`);
   await writeFile(join(TMP, "routes", "blog", "layout.tsx"), `export default function L({ children }: any) { return children; }\n`);
-  // Nested route — `routes/blog/layout.tsx` only applies because there is a
-  // deeper route under /blog/. Layouts wrap children, not the leaf at the
-  // same path level (matches `layout.ts`'s `layoutDirs` resolution).
+  // Nested route under /blog/ — `routes/blog/layout.tsx` wraps everything in
+  // its directory (including a `blog/_index`), per `layoutDirsFromFilePath`.
   await writeFile(join(TMP, "routes", "blog", "[slug].tsx"), `export default function P() { return null; }\n`);
 
   await writeFile(

package/src/__tests__/route-lint.test.ts

@@ -58,6 +58,11 @@ describe("lintRouteModuleSource — miscased exports", () => {
       `export default () => null;\n` +
       `export function loader() { return {}; }\n` +
       `export function action() { return {}; }\n` +
+      `export const clientLoader = () => ({});\n` +
+      `export const clientAction = () => ({});\n` +
+      `export function headers() { return {}; }\n` +
+      `export const middleware = [];\n` +
+      `export const handle = {};\n` +
       `export const searchSchema = {};\n` +
       `export function Fallback() { return null; }\n` +
       `export const ssr = false;\n`;

package/src/__tests__/route-middleware.test.ts

@@ -0,0 +1,84 @@
+import { test, expect, describe } from "bun:test";
+import {
+  runRouteMiddleware,
+  collectRouteMiddleware,
+  type RouteMiddleware,
+} from "../server/middleware.ts";
+import type { MiddlewareContext } from "../server/middleware.ts";
+
+function makeCtx(): MiddlewareContext {
+  return { request: new Request("http://localhost/"), params: {}, context: {} };
+}
+
+const ok = async () => new Response("ok", { status: 200 });
+
+describe("collectRouteMiddleware", () => {
+  test("orders root → layouts → route and flattens arrays", () => {
+    const order: string[] = [];
+    const mk = (label: string): RouteMiddleware => async (_c, n) => { order.push(label); return n(); };
+    const chain = {
+      root: { middleware: mk("root") },
+      layouts: [{ middleware: [mk("l0a"), mk("l0b")] }, { middleware: mk("l1") }],
+      route: { middleware: mk("route") },
+    };
+    const fns = collectRouteMiddleware(chain);
+    expect(fns).toHaveLength(5);
+    return runRouteMiddleware(fns, makeCtx(), ok).then(() => {
+      expect(order).toEqual(["root", "l0a", "l0b", "l1", "route"]);
+    });
+  });
+
+  test("ignores modules without middleware and non-function entries", () => {
+    const chain = {
+      root: {},
+      layouts: [{ middleware: undefined }, { middleware: ["nope" as unknown] }],
+      route: { middleware: (async (_c: MiddlewareContext, n: () => Promise<Response>) => n()) },
+    };
+    expect(collectRouteMiddleware(chain)).toHaveLength(1);
+  });
+});
+
+describe("runRouteMiddleware", () => {
+  test("empty list calls handler directly", async () => {
+    const res = await runRouteMiddleware([], makeCtx(), ok);
+    expect(res.status).toBe(200);
+  });
+
+  test("a middleware can short-circuit by not calling next()", async () => {
+    let handlerRan = false;
+    const gate: RouteMiddleware = async () => new Response("denied", { status: 403 });
+    const res = await runRouteMiddleware([gate], makeCtx(), async () => {
+      handlerRan = true;
+      return ok();
+    });
+    expect(res.status).toBe(403);
+    expect(handlerRan).toBe(false);
+  });
+
+  test("shares a mutable context across the chain and into the handler", async () => {
+    const ctx = makeCtx();
+    const setUser: RouteMiddleware = async (c, n) => { c.context.user = "alice"; return n(); };
+    let seenInHandler: unknown;
+    await runRouteMiddleware([setUser], ctx, async () => {
+      seenInHandler = ctx.context.user;
+      return ok();
+    });
+    expect(seenInHandler).toBe("alice");
+  });
+
+  test("rejects if a middleware calls next() twice", async () => {
+    const bad: RouteMiddleware = async (_c, n) => { await n(); return n(); };
+    await expect(runRouteMiddleware([bad], makeCtx(), ok)).rejects.toThrow(/more than once/);
+  });
+
+  test("outer middleware can post-process the inner Response", async () => {
+    const stamp: RouteMiddleware = async (_c, n) => {
+      const res = await n();
+      const out = new Response(res.body, res);
+      out.headers.set("X-Stamped", "1");
+      return out;
+    };
+    const res = await runRouteMiddleware([stamp], makeCtx(), ok);
+    expect(res.headers.get("X-Stamped")).toBe("1");
+  });
+});