npm - @bractjs/bractjs - Versions diffs - 0.1.24 → 0.1.26 - Mend

@bractjs/bractjs 0.1.24 → 0.1.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (46) hide show

package/README.md +755 -466
package/bin/cli.ts +23 -3
package/package.json +1 -1
package/src/__tests__/compile-safety.test.ts +163 -0
package/src/__tests__/compile-smoke.test.ts +276 -0
package/src/__tests__/csp.test.ts +80 -0
package/src/__tests__/fixtures/app/routes/_index.tsx +6 -2
package/src/__tests__/fixtures/app/routes/protected.tsx +15 -0
package/src/__tests__/fixtures/app/routes/redirect-action.tsx +13 -0
package/src/__tests__/integration.test.ts +62 -0
package/src/__tests__/layout-registry.test.ts +23 -0
package/src/__tests__/loader.test.ts +23 -0
package/src/__tests__/middleware.test.ts +22 -0
package/src/__tests__/programmatic-api.test.ts +41 -2
package/src/__tests__/response.test.ts +54 -1
package/src/__tests__/security.test.ts +35 -0
package/src/__tests__/server-module-stub.test.ts +145 -0
package/src/__tests__/stream-handler.test.ts +36 -0
package/src/build/bundler.ts +46 -20
package/src/build/directives.ts +2 -2
package/src/build/env-plugin.ts +76 -5
package/src/build/react-dedupe.ts +41 -0
package/src/client/ClientRouter.tsx +22 -8
package/src/client/components/Form.tsx +10 -1
package/src/client/hooks/useFetcher.ts +17 -1
package/src/client/nav-utils.ts +54 -3
package/src/client/types.ts +3 -0
package/src/config/load.ts +50 -2
package/src/dev/devtools.ts +72 -39
package/src/dev/hmr-module-handler.ts +6 -4
package/src/dev/rebuilder.ts +16 -1
package/src/dev/server.ts +3 -0
package/src/index.ts +13 -3
package/src/server/csp.ts +92 -0
package/src/server/csrf.ts +44 -6
package/src/server/layout.ts +12 -2
package/src/server/loader.ts +5 -7
package/src/server/render.ts +29 -10
package/src/server/request-handler.ts +15 -4
package/src/server/response.ts +58 -5
package/src/server/serve.ts +10 -0
package/src/server/static.ts +11 -1
package/src/server/stream-handler.ts +8 -7
package/src/server/use-client-runtime.ts +62 -0
package/src/shared/meta-tags.tsx +46 -0
package/types/index.d.ts +20 -2

package/README.md CHANGED Viewed

@@ -1,27 +1,152 @@
 # BractJS
-> Production-grade SSR framework for Bun + React.
-> File-based routing · Parallel loaders · Streaming SSR · Built-in HMR · Server Actions
+[![npm version](https://img.shields.io/npm/v/@bractjs/bractjs)](https://www.npmjs.com/package/@bractjs/bractjs)
+[![license](https://img.shields.io/npm/l/@bractjs/bractjs)](LICENSE)
+> Production-grade SSR framework for **Bun + React 19**.
+> File-based routing · Parallel loaders · Streaming SSR · Built-in HMR · Server Actions · Typed routes · Single-binary deploy.
+## Requirements
+- [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)).
+---
+## Table of Contents
+1. [Install & create an app](#1-install--create-an-app)
+2. [Project structure](#2-project-structure)
+3. [The root layout (`app/root.tsx`)](#3-the-root-layout-approotsx)
+4. [File-based routing](#4-file-based-routing)
+5. [Route module API: `loader`, `action`, `meta`, `beforeLoad`, `ErrorBoundary`, `default`](#5-route-module-api)
+6. [Response helpers: `json`, `redirect`, `error`, `HttpError`](#6-response-helpers)
+7. [Per-route context: `defineContext`](#7-per-route-context-definecontext)
+8. [Streaming data: `defer`, `Deferred`, `isDeferred`, `<Await>`](#8-streaming-data)
+9. [Client hooks](#9-client-hooks)
+10. [Client components: `<Outlet>`, `<Link>`, `<Form>`, `<Scripts>`, `<LiveReload>`, `<Image>`](#10-client-components)
+11. [Server Actions (`"use server"`) & client-only (`"use client"`)](#11-server-actions--client-components)
+12. [Typed API routes: `route` + `createClient`](#12-typed-api-routes)
+13. [Input validation: `validate`](#13-input-validation-validate)
+14. [Middleware: `pipeline`, `requestLogger`, `cors`, `authGuard`, `csp`](#14-middleware)
+15. [Sessions: `createCookieSession`](#15-sessions)
+16. [Lifecycle hooks: `defineLifecycle`](#16-lifecycle-hooks)
+17. [Environment variables & `*.server.ts`](#17-environment-variables)
+18. [Typed routes codegen](#18-typed-routes-codegen)
+19. [Internationalization (i18n) utilities](#19-internationalization-utilities)
+20. [Image optimization (`<Image>` + `/_image`)](#20-image-optimization)
+21. [Build & run: CLI + programmatic API (`createDevServer`, `runBuild`, `loadUserConfig`)](#21-build--run)
+22. [Single-binary deployment (`bun build --compile`)](#22-single-binary-deployment)
+23. [Custom adapters (`BunAdapter`, Cloudflare)](#23-custom-adapters)
+24. [Build plugins (for custom `Bun.build`)](#24-build-plugins)
+25. [Configuration reference](#25-configuration-reference)
+26. [Full export index](#26-full-export-index)
 ---
-## Quick Start
+## 1. Install & create an app
+BractJS requires [Bun](https://bun.sh). There is no Node.js runtime path.
 ```sh
-# Requires Bun — https://bun.sh
+# Scaffold a new app
 bunx bractjs new my-app
 cd my-app
+# Start the dev server (HMR on http://localhost:3000)
 bun run dev
-# → http://localhost:3000
 ```
-> **From source (pre-publish):** clone the repo, then `bun run bin/cli.ts new my-app`.
+`bractjs new <name>` copies the scaffold template, runs `bun install`, and seeds `app/_generated/` so the single-binary entry typechecks before your first build.
+Add it to an existing project instead:
+```sh
+bun add @bractjs/bractjs react react-dom
+```
+`react` and `react-dom` v19 are **peer dependencies** — BractJS ships zero other runtime deps.
+---
+## 2. Project structure
+```
+my-app/
+├── app/
+│   ├── root.tsx              # required — the <html> document shell
+│   ├── server.ts             # single-binary entry (bun build --compile)
+│   ├── lifecycle.ts          # optional — onStart / onShutdown / onError
+│   ├── route-types.gen.ts    # generated by `bractjs codegen`
+│   ├── _generated/           # generated by `bractjs codegen:registry` / `:manifest`
+│   ├── actions.ts            # "use server" actions (optional)
+│   └── routes/
+│       ├── _index.tsx        # → /
+│       ├── about.tsx         # → /about
+│       ├── blog/
+│       │   ├── layout.tsx    # wraps /blog/*
+│       │   ├── _index.tsx    # → /blog
+│       │   └── [id].tsx      # → /blog/:id
+│       └── docs/
+│           └── [...slug].tsx # → /docs/*  (catch-all)
+├── public/                   # static assets, served at /public/*
+├── bractjs.config.ts         # optional config (see §25)
+└── build/                    # generated — do not edit
+```
+Defaults: `appDir="./app"`, `publicDir="./public"`, `buildDir="./build"`, `port=3000`. All overridable (§25).
+---
+## 3. The root layout (`app/root.tsx`)
+**Required.** It provides the `<html>` document shell and is always rendered. Use the `<Outlet>`, `<Scripts>`, and `<LiveReload>` components from the package.
+```tsx
+// app/root.tsx
+import { Outlet, Scripts, LiveReload } from "@bractjs/bractjs";
+export function meta() {
+  return [
+    { title: "My App" },
+    { name: "viewport", content: "width=device-width, initial-scale=1" },
+  ];
+}
+export default function Root() {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        {/* BractJS hoists <title>/<meta> from every route's meta() into <head> */}
+      </head>
+      <body>
+        <Outlet />     {/* renders the matched route tree */}
+        <Scripts />    {/* injects the client bundle + bootstrap data */}
+        <LiveReload /> {/* dev-only HMR client; no-op in production */}
+      </body>
+    </html>
+  );
+}
+```
+**Step by step:**
+1. `export default function Root()` returns the full `<html>` document.
+2. Put `<Outlet />` where the page content should render.
+3. Put `<Scripts />` at the end of `<body>` — it's a marker the SSR pipeline replaces with the hashed client entry + `window.__BRACTJS_DATA__`.
+4. `<LiveReload />` renders an HMR client script in dev and `null` in production.
+5. Optionally `export function meta()` for site-wide defaults (route `meta()` overrides per descriptor).
+> `<title>`/`<meta>` tags from any route's `meta()` are rendered into `<head>` via React 19 document-metadata hoisting — you do not place them manually.
 ---
-## File-Based Routing
+## 4. File-based routing
-Place files inside `app/routes/`. BractJS scans them at startup.
+Drop a file in `app/routes/`; it becomes a route. BractJS scans at startup and builds a trie.
 | File | URL |
 |------|-----|
@@ -32,95 +157,162 @@ Place files inside `app/routes/`. BractJS scans them at startup.
 | `routes/docs/[...slug].tsx` | `/docs/*` (catch-all) |
 | `routes/blog/layout.tsx` | wraps all `/blog/*` routes |
-`app/root.tsx` is the outermost layout (always rendered). Match priority per segment: **static > dynamic > catch-all**.
+- `[param]` → a dynamic segment, read via `useParams()` / `params` arg.
+- `[...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**.
+No registration step — the file IS the route.
 ---
-## Route Module API
+## 5. Route module API
-Every file in `app/routes/` can export any combination of these:
+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 { redirect } from "@bractjs/bractjs";
+import { redirect, json, HttpError } from "@bractjs/bractjs";
-// Runs on every GET — return value becomes useLoaderData()
+// 1) loader — runs on every GET. Return value → useLoaderData().
 export async function loader({ request, params, context }: LoaderArgs) {
   const post = await db.post.findById(params.id);
-  if (!post) throw new Response("Not Found", { status: 404 });
+  if (!post) throw new HttpError(404, "Not found"); // → 404 page
   return { post };
 }
 export type LoaderData = Awaited<ReturnType<typeof loader>>;
-// Runs on POST / PUT / DELETE
-export async function action({ params, formData }: ActionArgs) {
+// 2) action — runs on POST / PUT / DELETE / PATCH.
+export async function action({ request, params, context, formData }: ActionArgs) {
   await db.post.update(params.id, { title: formData.get("title") as string });
   return redirect("/blog");
 }
-// SSR <title> and <meta> tags
-export function meta({ loaderData }: MetaArgs<LoaderData>) {
+// 3) meta — SSR <title> / <meta>. Receives this route's loaderData slice.
+export function meta({ loaderData, params }: MetaArgs<LoaderData>) {
   return [
     { title: loaderData.post.title },
     { name: "description", content: loaderData.post.excerpt },
+    { property: "og:title", content: loaderData.post.title },
   ];
 }
-// Error boundary for this route segment
-export function ErrorBoundary({ error }: { error: Error }) {
-  return <p>Error: {error.message}</p>;
+// 4) beforeLoad — auth/redirect gate. Runs BEFORE loaders, on full-page GET
+//    AND the /_data soft-nav endpoint. Return a Response to short-circuit.
+export function beforeLoad({ context, params, location }) {
+  if (!context.user) {
+    return redirect(`/login?next=${encodeURIComponent(location.pathname)}`);
+  }
+}
+// 5) ErrorBoundary — renders when this segment's loader/component throws.
+export function ErrorBoundary({ error }: { error: unknown }) {
+  return <p>Something broke: {error instanceof Error ? error.message : String(error)}</p>;
 }
-// The page component (required)
+// 6) default — the page component (required for a renderable route).
 export default function BlogPost() {
   const { post } = useLoaderData<LoaderData>();
   return <article><h1>{post.title}</h1></article>;
 }
 ```
+**Execution order for a request:**
+```
+beforeLoad → (action, if mutating method) → loaders (root + layouts + route, in parallel) → render
+```
+- **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`.
+> **Security:** put auth checks in `beforeLoad` (per route) or middleware (cross-cutting) — never in a component. `/_data` (used by `<Link>` soft-nav) runs `beforeLoad` and the loader, so a component-only check would still leak loader JSON. See §14.
 ---
-## Root Layout (`app/root.tsx`)
+## 6. Response helpers
-Required. Provides the `<html>` document shell.
+Imported from `@bractjs/bractjs`.
-```tsx
-import { Scripts, LiveReload, Outlet } from "@bractjs/bractjs";
+```ts
+import { json, redirect, error, HttpError, isRedirect, isHttpError } from "@bractjs/bractjs";
+```
-export function meta() {
-  return [{ title: "My App" }, { name: "viewport", content: "width=device-width, initial-scale=1" }];
+### `json(data, init?)`
+Serialize a value as `application/json`.
+```ts
+return json({ ok: true }, { status: 201 });
+```
+### `redirect(url, status?, headers?, options?)`
+Throw or return a redirect. **Open-redirect safe by default** — rejects `//evil.com`, `/\evil`, `https://…`, `javascript:` unless you pass `{ allowExternal: true }`.
+```ts
+return redirect("/dashboard");                                   // 302
+return redirect("/login", 303);                                  // custom status
+return redirect("/x", 302, { "Set-Cookie": cookie });            // with headers
+return redirect("https://other.com", 302, undefined, { allowExternal: true });
+```
+### `error(message, status?)`
+Convenience JSON error: `{ "error": message }` with the given status (default 500).
+```ts
+return error("Bad Request", 400);
+```
+### `HttpError` & `BractJSError`
+Throw a typed HTTP error from a loader/action. The framework converts it to a response with that status (and a default status text if you omit the message).
+```ts
+throw new HttpError(403);                 // → 403 Forbidden
+throw new HttpError(404, "No such post"); // → 404 with custom message
+```
+`isRedirect(value)` / `isHttpError(value)` / `isBractJSError(value)` are type guards if you handle errors manually.
+---
+## 7. Per-route context: `defineContext`
+A route can compute request-scoped data once and share it with all its loaders/actions via the `context` argument. Middleware can also populate `context` (§14) — `defineContext` is the per-route version.
+```ts
+// app/routes/dashboard.tsx
+import { defineContext } from "@bractjs/bractjs";
+import { getUser } from "../auth.server.ts";
+export const context = defineContext(async ({ request, params }) => ({
+  user: await getUser(request),
+}));
+export function beforeLoad({ context }) {
+  if (!context.user) return redirect("/login");
 }
-export default function Root() {
-  return (
-    <html lang="en">
-      <head>{/* BractJS injects <title> and <meta> tags here */}</head>
-      <body>
-        <Outlet />     {/* current route tree */}
-        <Scripts />    {/* client bundle */}
-        <LiveReload /> {/* dev-only HMR — no-op in production */}
-      </body>
-    </html>
-  );
+export async function loader({ context }) {
+  return { name: context.user.name };
 }
 ```
+The factory runs before `beforeLoad` and its result is merged into `context` for `beforeLoad`, `loader`, and `action` on that route.
 ---
-## Deferred / Streaming Data
+## 8. Streaming data
-`defer()` streams slow data without blocking the initial HTML response.
+Stream slow data without blocking the initial HTML.
-```tsx
-import { defer } from "@bractjs/bractjs";
+```ts
+import { defer, Deferred, isDeferred } from "@bractjs/bractjs";
 import { Await } from "@bractjs/bractjs";
 import { Suspense } from "react";
+```
+### `defer(data)`
+Wraps each `Promise` field in a `Deferred`; non-promise fields pass through. Awaited fields are in the initial HTML; promises stream after.
+```tsx
 export async function loader({ params }: LoaderArgs) {
   return defer({
-    post: await db.post.findById(params.id),  // awaited — in initial HTML
-    comments: db.comments.forPost(params.id), // Promise — streamed later
+    post: await db.post.findById(params.id),  // awaited → initial HTML
+    comments: db.comments.forPost(params.id), // Promise → streamed
   });
 }
@@ -139,176 +331,123 @@ export default function BlogPost() {
 }
 ```
----
+### `<Await resolve={promise} fallback={…}>{(data) => …}</Await>`
+Unwraps a promise with React 19's `use()` inside its own `<Suspense>`. `isDeferred(value)` and the `Deferred` class are exported if you need to detect/construct deferred values manually.
-## Client Primitives
-### `<Link>`
+---
-Soft-navigates without a full reload. `prefetch="hover"` preloads the route chunk + loader data on mouse-enter.
+## 9. Client hooks
-```tsx
-import { Link } from "@bractjs/bractjs";
+All hooks are SSR-safe (they return sensible values during SSR) and imported from `@bractjs/bractjs`.
-<Link to="/blog/42">Read Post</Link>
-<Link to="/about" prefetch="hover">About</Link>
+### `useLoaderData<T>()` → `T`
+The current route's loader return value.
+```ts
+const { post } = useLoaderData<LoaderData>();
 ```
-### `<Form>`
-Fetch-based submission. Re-runs the current route's loader after the action completes.
-```tsx
-import { Form } from "@bractjs/bractjs";
-<Form method="post" action="/blog/new">
-  <input name="title" />
-  <button type="submit">Create</button>
-</Form>
+### `useActionData<T>()` → `T | null`
+The most recent action return value (null until an action runs).
+```ts
+const result = useActionData<{ error?: string }>();
 ```
-### `<Outlet>`
-Renders the matched child route inside a layout.
-```tsx
-export default function BlogLayout() {
-  return (
-    <div>
-      <nav>Blog</nav>
-      <Outlet />
-    </div>
-  );
-}
+### `useParams<T>()` → `T`
+URL dynamic params. Pass a generic for typed params.
+```ts
+const { id } = useParams<{ id: string }>();
 ```
----
-## Hooks
-| Hook | Returns | Description |
-|------|---------|-------------|
-| `useLoaderData<T>()` | `T` | Loader return value for the current route |
-| `useActionData<T>()` | `T \| null` | Most recent action return value |
-| `useParams<T>()` | `T` | URL dynamic params (generic for typed params) |
-| `useNavigation()` | `{ state }` | `"idle"` \| `"loading"` \| `"submitting"` |
-| `useFetcher()` | `{ data, state, load, submit }` | Background fetch without navigation |
-```tsx
-import { useLoaderData, useNavigation, useFetcher } from "@bractjs/bractjs";
-const { post } = useLoaderData<LoaderData>();
+### `useNavigation()` → `{ state }`
+`"idle" | "loading" | "submitting"`.
+```ts
 const { state } = useNavigation();
 if (state === "loading") return <Spinner />;
-const fetcher = useFetcher();
-fetcher.load("/api/suggestions?q=bun");
 ```
----
-## Image Optimization
-`<Image>` serves responsively-sized, format-converted images through a built-in `/_image` endpoint. Requires [ImageMagick](https://imagemagick.org) (`magick` or `convert`) — falls back to serving the original if not installed.
-```tsx
-import { Image } from "@bractjs/bractjs";
-// Basic — lazy, WebP, 80% quality, responsive srcset
-<Image src="/public/hero.jpg" alt="Hero" width={1200} height={600} />
-// Above-the-fold — eager load + fetchpriority=high
-<Image src="/public/hero.jpg" alt="Hero" width={1200} priority />
-// Custom format / quality / fit
-<Image
-  src="/public/photo.jpg"
-  alt="Photo"
-  width={800}
-  format="avif"
-  quality={70}
-  fit="contain"
-  sizes="(max-width: 640px) 100vw, 50vw"
-/>
+### `useSearchParams<T>()` → `{ searchParams, getParam, setSearchParams }`
+Read/write URL query params; writing triggers a soft-nav loader re-run.
+```ts
+const { searchParams, getParam, setSearchParams } = useSearchParams<{ q: string }>();
+const q = getParam("q");                       // string | null
+setSearchParams({ q: "bun" });                 // replace all params
+setSearchParams((prev) => { prev.set("page", "2"); return prev; }); // update
 ```
-The component generates a `srcset` across up to 7 breakpoints (320 → 1920 px). Optimized images are cached in memory (LRU, 200 slots) and on disk (`.bract-image-cache/`, survives restarts). Both layers respond with `Cache-Control: immutable`.
-**Props:**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | — | Path under `/public/` |
-| `alt` | `string` | — | Alt text (required) |
-| `width` | `number` | — | Intrinsic width |
-| `height` | `number` | — | Intrinsic height |
-| `quality` | `number` | `80` | 1–100 |
-| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | `"webp"` | Output format |
-| `fit` | `"cover" \| "contain" \| "fill"` | `"cover"` | Resize mode |
-| `priority` | `boolean` | `false` | Disable lazy loading, set `fetchpriority=high` |
-| `sizes` | `string` | `"100vw"` | HTML `sizes` attribute |
----
-## Typed Routes (Codegen)
-Run `bractjs codegen` to generate `app/route-types.gen.ts` from your route files. This runs automatically during `bractjs build`.
-```sh
-bractjs codegen            # reads ./app, writes ./app/route-types.gen.ts
-bractjs codegen ./app ./app/route-types.gen.ts  # explicit paths
+### `useFetcher()` → `{ data, state, load, submit }`
+Background fetch without navigating.
+```ts
+const fetcher = useFetcher();
+await fetcher.load("/products?q=bun");                       // GET loader data
+await fetcher.submit("/cart", { method: "post", body: { id: "1" } });
 ```
-**Generated file provides:**
+### `useFetcher<T>({ stream: true })` → `{ connect }`
+Consume an async-generator server action as an SSE stream.
 ```ts
-// Every URL pattern as a string literal union
-export type AppRoutes = "/" | "/blog/:id" | "/org/:orgId/repo/:repoId";
-// Per-route typed params
-export type RouteParams<T extends AppRoutes> =
-  T extends "/blog/:id" ? { id: string } :
-  T extends "/org/:orgId/repo/:repoId" ? { orgId: string; repoId: string } :
-  Record<never, never>;
+const { connect } = useFetcher<string>({ stream: true });
+for await (const chunk of connect(actionId)) { /* … */ }
+```
-// Typed loader / action args
-export type TypedLoaderArgs<T extends AppRoutes> = { request: Request; params: RouteParams<T>; context: Record<string, unknown> };
-export type TypedActionArgs<T extends AppRoutes> = TypedLoaderArgs<T> & { formData: FormData };
+### `useBlocker(shouldBlock)`
+Prompt before leaving when there are unsaved changes (intercepts back/forward and `<Link>` navigations).
+```ts
+useBlocker(() => formIsDirty);
+```
-// Type-safe route builder
-export const routes = {
-  "/": () => "/",
-  "/blog/:id": (params: { id: string }) => `/blog/${params.id}`,
-} as const;
+### `useLocale(defaultLocale?)` → `string` and `useLocalizedLink(defaultLocale?)` → `(path) => string`
+For i18n prefix routing (§19).
+```ts
+const locale = useLocale("en");                 // reads params.locale
+const localized = useLocalizedLink("en");
+<Link to={localized("/about")} />               // → /en/about
 ```
-**Usage:**
+---
-```ts
-// Typed loader — params.id is string, not string | undefined
-import type { TypedLoaderArgs, RouteParams } from "../route-types.gen.ts";
+## 10. Client components
-export async function loader({ params }: TypedLoaderArgs<"/blog/:id">) {
-  return db.post.findById(params.id); // ✓ typed
+### `<Outlet />`
+Renders the matched child route inside a layout (or the route tree inside `root.tsx`).
+```tsx
+export default function BlogLayout() {
+  return <div><nav>Blog</nav><Outlet /></div>;
 }
+```
-// Typed params hook
-const { id } = useParams<RouteParams<"/blog/:id">>();
+### `<Link to prefetch? viewTransition?>`
+Soft-navigates without a full reload.
+```tsx
+<Link to="/blog/42">Read</Link>
+<Link to="/about" prefetch="hover">About</Link>   {/* preload chunk + loader on hover */}
+<Link to="/gallery" viewTransition>Gallery</Link> {/* use View Transitions API */}
+```
+Modifier-clicks (ctrl/cmd/shift/alt) fall back to native browser navigation.
-// Type-safe navigation
-import { routes } from "../route-types.gen.ts";
-routes["/blog/:id"]({ id: "123" });         // → "/blog/123"
-routes["/does-not-exist"]();                 // ✗ TypeScript error
+### `<Form method action?>`
+Fetch-based submission that re-runs the current route's loader after the action.
+```tsx
+<Form method="post">
+  <input name="title" />
+  <button type="submit">Create</button>
+</Form>
+<Form method="post" action="/blog/new">…</Form>
 ```
+Submits as `multipart/form-data` with the `X-BractJS-Action` header (CSRF gate). If the action returns a redirect, the form follows it.
+### `<Scripts />` and `<LiveReload />`
+Markers used inside `root.tsx` (§3). `<Scripts />` is where the client bundle + bootstrap data go; `<LiveReload />` is the dev-only HMR client.
+### `<Image />`
+Responsive, format-converted images via the built-in `/_image` endpoint — see §20.
 ---
-## Server Actions & Client Components
+## 11. Server Actions & Client Components
 ### `"use server"` — Server Actions
-Add `"use server"` as the first line of a file to mark its exports as Server Actions. On the client, calls are automatically serialized to `POST /_action?id=<hash>`. On the server, the real function runs.
+Mark a file's exports as server actions by making `"use server"` the first line. On the **client**, imports become `fetch("/_action?id=<hash>")` proxies; on the **server**, the real function runs. Action IDs are `SHA-256(appDir-relative-path + "#" + name)`.
 ```ts
 // app/actions.ts
@@ -326,7 +465,7 @@ export async function deletePost(id: string) {
 ```
 ```tsx
-// app/routes/new.tsx — import used normally; on client it becomes a fetch proxy
+// app/routes/new.tsx — import as normal; the client bundle gets a fetch proxy
 import { createPost } from "../actions.ts";
 export default function NewPost() {
@@ -339,11 +478,15 @@ export default function NewPost() {
 }
 ```
-Server actions accept `FormData` (sent as `multipart/form-data`) or JSON-serializable argument arrays. Unknown action IDs return 404 — there is no way to call a function that was not registered at startup.
+- Accepts a single `FormData` (sent as `multipart/form-data`) **or** a JSON-serializable argument array.
+- Unknown action IDs return 404 — only functions registered at startup are callable.
+- Bodies are size-capped (1 MiB JSON) and prototype-pollution scanned.
+**Streaming server actions** (async generators) are consumed with `useFetcher({ stream: true })` (§9) over `/_stream`. The endpoint requires the `X-BractJS-Action` header (set automatically by the client).
 ### `"use client"` — Client-Only Components
-Add `"use client"` to mark a component as browser-only. During server builds the module is stubbed to `null` to prevent browser API (`window`, `document`, `localStorage`) crashes.
+Mark a component browser-only. During server builds the module is stubbed to `null` to prevent `window`/`document`/`localStorage` crashes during SSR.
 ```tsx
 // app/components/Counter.tsx
@@ -358,53 +501,148 @@ export function Counter() {
 ---
-## Middleware
+## 12. Typed API routes
-Middleware runs before routing. Register on the module-level `pipeline` singleton.
+Define type-safe JSON endpoints under `/api/*` with `route`, and call them with a fully-typed `createClient`.
+### Define routes with `route(method, path, handler)`
 ```ts
-import { pipeline, requestLogger, cors, authGuard } from "@bractjs/bractjs";
+// app/api/users.ts
+import { route } from "@bractjs/bractjs";
+import { db } from "../db.server.ts";
+export const listUsers = route("GET", "/api/users", async () => {
+  return db.users.findAll();
+});
+export const createUser = route("POST", "/api/users", async (input: { name: string }) => {
+  return db.users.create(input);
+});
+```
+- `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).
+- 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`).
+### Call them with `createClient<AppApiRoutes>()`
+```ts
+import { createClient } from "@bractjs/bractjs";
+import type { AppApiRoutes } from "@bractjs/bractjs"; // union of your route defs
+const client = createClient<AppApiRoutes>();          // optional baseUrl arg
+const users = await client["/api/users"].GET();        // typed output
+await client["/api/users"].POST({ name: "Alice" });    // typed input
+```
+The proxy builds `METHOD path` from the property chain. Non-2xx responses throw an `Error` with `.status` and `.response` attached.
+---
+## 13. Input validation: `validate`
+Validate `FormData` or a plain object against any **Zod- or Valibot-compatible** schema (anything with `.safeParse()` or `.parse()`).
+```ts
+import { validate } from "@bractjs/bractjs";
+import { z } from "zod";
+const Schema = z.object({ title: z.string().min(1), tags: z.array(z.string()) });
+export async function action({ formData }: ActionArgs) {
+  // Throws a 400 Response with { errors: { field: [msgs] } } on failure.
+  const data = await validate(Schema, formData);
+  await db.post.create(data); // data is fully typed + coerced
+}
+```
+- Repeated `FormData` keys become arrays automatically.
+- On failure it throws a `Response.json({ errors }, { status: 400 })`. The exported `ValidationError` type and `FieldErrors` shape describe the structure.
+---
+## 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.
+```ts
+import { pipeline, requestLogger, cors, authGuard, csp } from "@bractjs/bractjs";
+import type { MiddlewareFn } from "@bractjs/bractjs";
 pipeline
   .use(requestLogger())
   .use(cors({ origin: "https://myapp.com" }))
+  .use(csp())
   .use(authGuard({ session }));
 ```
-| Middleware | Description |
+### Built-in middleware
+| Middleware | What it does |
 |---|---|
-| `requestLogger()` | Logs method, path, status, duration |
-| `cors(options)` | Sets CORS headers, handles `OPTIONS` preflight |
-| `authGuard(options)` | Reads session, attaches `context.user`, returns 401 if unauthenticated |
+| `requestLogger()` | Logs `[METHOD] /path → status in Xms`. Never logs the query string or headers (token-leak safe). |
+| `cors(options)` | Sets CORS headers, handles `OPTIONS` preflight (204), always sets `Vary: Origin`, refuses `credentials:true` + `origin:"*"`. |
+| `authGuard(options)` | Reads the session, sets `ctx.context.user`; with `required:true` returns 401 when unauthenticated. |
+| `csp(options?)` | Opt-in nonce-based Content-Security-Policy (see below). |
-**Custom middleware:**
+**`cors(options)`** — `{ origin: string | string[]; methods?: string[]; credentials?: boolean }`:
+```ts
+pipeline.use(cors({ origin: ["https://a.com", "https://b.com"], credentials: true }));
+```
+**`authGuard(options)`** — `{ session: SessionStorageLike; required?: boolean }`:
+```ts
+pipeline.use(authGuard({ session, required: true })); // 401 if no session.user
+```
+**`csp(options?)`** — generates a per-request nonce, applies it to the scripts BractJS injects (via `renderToReadableStream`'s `nonce`), and sets the CSP header:
+```ts
+pipeline.use(csp({
+  directives: { "img-src": "'self' data: https://cdn.example", "frame-ancestors": "'none'" },
+  reportOnly: false, // true → Content-Security-Policy-Report-Only
+}));
+```
+Read the nonce inside a component/middleware with `getCspNonce(context)` (key: `CSP_NONCE_KEY`) to nonce your own inline scripts.
+### Custom middleware
 ```ts
 import type { MiddlewareFn } from "@bractjs/bractjs";
 const trace: MiddlewareFn = async (ctx, next) => {
   ctx.context.requestId = crypto.randomUUID();
-  return next();
+  const res = await next();
+  res.headers.set("X-Request-Id", ctx.context.requestId as string);
+  return res;
 };
+pipeline.use(trace);
 ```
-`ctx.context` is threaded into every `loader` and `action` as the `context` argument.
+You can also construct an isolated `new MiddlewarePipeline()` and `.run(ctx, handler)` it yourself (used internally and in tests).
 ---
-## Sessions
+## 15. Sessions
+Signed, tamper-proof cookie sessions (HMAC-SHA256, constant-time verify, secret rotation).
 ```ts
 import { createCookieSession } from "@bractjs/bractjs";
 const session = createCookieSession({
   name: "__session",
-  secrets: [Bun.env.SESSION_SECRET],  // rotate: prepend new secret, keep old ones
-  maxAge: 60 * 60 * 24 * 7,           // 1 week
-  secure: true,
-  sameSite: "lax",
+  secrets: [Bun.env.SESSION_SECRET!], // first signs; all verify (rotate by prepending)
+  maxAge: 60 * 60 * 24 * 7,           // seconds; 1 week
+  secure: true,                        // false only for local HTTP dev
+  sameSite: "Lax",                     // "Strict" | "Lax" | "None"
 });
+```
+Read in a loader, write in an action:
+```ts
 export async function loader({ request }: LoaderArgs) {
   const s = await session.getSession(request.headers.get("Cookie"));
   return { user: s.get("user") };
@@ -412,406 +650,457 @@ export async function loader({ request }: LoaderArgs) {
 export async function action({ request }: ActionArgs) {
   const s = await session.getSession(request.headers.get("Cookie"));
-  s.set("user", { id: 1, name: "Alice" });
+  s.set("user", { id: 1, name: "Alice" }); // also: s.get, s.has, s.delete
   return redirect("/dashboard", {
-    headers: { "Set-Cookie": await session.commitSession(s) },
+    headers: { "Set-Cookie": await session.commitSession(s) }, // opt: { maxAge }
   });
 }
 ```
-Cookies are signed with HMAC-SHA256 using `crypto.subtle`. Tampered cookies are silently rejected and return an empty session.
-> Generate a secret: `openssl rand -base64 32`
+- Each secret must be ≥16 chars; `secrets` must be non-empty (throws otherwise).
+- Tampered cookies are silently rejected → empty session.
+- Generate a secret: `openssl rand -base64 32`.
 ---
-## Environment Variables
+## 16. Lifecycle hooks: `defineLifecycle`
-| Convention | Behavior |
-|---|---|
-| `*.server.ts` / `*.server.tsx` | Import blocked in client bundles at build time — hard error |
-| Keys in `clientEnv` | Replaced with string literals in client bundle |
-| All other `process.env.*` | Become `"undefined"` in client bundles |
-```ts
-// db.server.ts — never reaches the browser
-export const db = new Database(Bun.env.DATABASE_URL);
-```
----
-## Server Lifecycle Hooks
-Use `defineLifecycle()` in `app/lifecycle.ts` to run code when the server starts, shuts down, or encounters an error. The shutdown hook runs on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, and uncaught exceptions), so database connections are always closed cleanly.
+Run code on server start, shutdown, and unexpected errors. Shutdown fires on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, uncaught exceptions).
 ```ts
 // app/lifecycle.ts
 import { defineLifecycle } from "@bractjs/bractjs";
 import { db } from "./db.server.ts";
-import * as Sentry from "@sentry/bun";
 export default defineLifecycle({
-  async onStart() {
-    await db.connect();
-    console.log("Database connected");
-  },
-  async onShutdown() {
-    await db.disconnect();
-    console.log("Database disconnected");
-  },
-  async onError(err, request) {
-    // request is undefined for process-level uncaught exceptions
-    Sentry.captureException(err, {
-      extra: { url: request?.url },
-    });
+  async onStart()   { await db.connect();    },
+  async onShutdown(){ await db.disconnect(); },
+  onError(err, request) {
+    Sentry.captureException(err, { extra: { url: request?.url } });
   },
 });
 ```
-BractJS picks up `app/lifecycle.ts` automatically in dev mode. In production, spread the hooks into `createServer()`:
+| Hook | When |
+|------|------|
+| `onStart` | Once, after the server starts listening. |
+| `onShutdown` | Before exit — any signal, programmatic `stop()`, or uncaught exception. |
+| `onError` | Every unexpected error (loader/action throws, uncaught exceptions). Redirects and `HttpError`s are intentional control flow and are **not** reported. `request` is `undefined` for process-level exceptions. |
-```ts
-// server.ts (production entry)
-import { createServer } from "@bractjs/bractjs";
-import lifecycle from "./app/lifecycle.ts";
+- **Dev** picks up `app/lifecycle.ts` automatically.
+- **Production**: spread into `createServer()`:
+  ```ts
+  import { createServer } from "@bractjs/bractjs";
+  import lifecycle from "./app/lifecycle.ts";
+  createServer({ port: 3000, ...lifecycle });
+  ```
-createServer({ port: 3000, ...lifecycle });
-```
+`createServer()` returns `{ stop }`. `stop()` runs `onShutdown` and closes the listener but does **not** call `process.exit()` (good for tests/supervisors). Signals do exit.
-| Hook | When it runs |
-|------|-------------|
-| `onStart` | Once, after the server begins accepting requests |
-| `onShutdown` | Before process exit — any signal, programmatic `stop()`, or uncaught exception |
-| `onError` | Every unexpected error: loader failures, action throws, uncaught exceptions. Redirects and `HttpError` throws are intentional control flow and are **not** reported. |
+---
-### Programmatic stop vs signal-driven termination
+## 17. Environment variables
-`createServer()` returns a `{ stop }` handle:
+| Convention | Behavior |
+|---|---|
+| `*.server.ts` / `*.server.tsx` | **Stubbed out of the client bundle.** Import it freely from a route's `loader`/`action`; every export is replaced by an inert stub in the browser build, so the real source (DB drivers, secrets, `bun:sqlite`) never ships. The stub throws if you accidentally call it on the client. |
+| Keys listed in `clientEnv` | Replaced with string literals in the client bundle. |
+| Any other `process.env.*` | Becomes the literal `"undefined"` in the client bundle. |
 ```ts
-const srv = createServer({ port: 3000 });
-// later:
-srv.stop();          // runs onShutdown, closes the listener, does NOT exit the process
+// db.server.ts — never reaches the browser
+import { Database } from "bun:sqlite";
+export const db = new Database(Bun.env.DATABASE_URL!);
 ```
-`stop()` returns the process to a normal idle state — useful in tests, integration harnesses, or any parent that wants to manage its own lifecycle. It does **not** call `process.exit()`.
+```ts
+// app/routes/posts.tsx — import the server module inside the loader
+import { db } from "../db.server.ts"; // stubbed in the client bundle
-The full termination path (`process.exit(0)`) only fires when a signal handler picks up the shutdown: `SIGTERM`, `SIGINT`, `SIGUSR2`, or `uncaughtException`. If you want a programmatic stop to terminate the process, call `process.exit(0)` yourself after `stop()` returns.
+export async function loader() {
+  return { posts: db.query("SELECT * FROM posts").all() };
+}
+```
----
+> BractJS ships the whole route module — `loader` and `action` included — to the client, so a server import is reachable from the client graph. The `serverModuleStubPlugin` (applied automatically by `bractjs dev`/`build`) replaces every `*.server.ts` export with a throwing stub: the import resolves, the loader/action are dead code on the client, and **zero** server source is emitted. The stricter, hard-failing `serverOnlyPlugin` is still exported if you'd rather a server import be a build error.
-## Configuration Reference
+```ts
+// bractjs.config.ts
+export default { clientEnv: ["PUBLIC_API_URL"] };
+```
-All fields are optional. BractJS works with zero configuration.
+```ts
+// in a client component — only allow-listed keys survive
+fetch(`${process.env.PUBLIC_API_URL}/items`);
+```
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `port` | `number` | `3000` | TCP port |
-| `appDir` | `string` | `"./app"` | Directory containing `routes/` and `root.tsx` |
-| `publicDir` | `string` | `"./public"` | Static assets (served with no-cache) |
-| `buildDir` | `string` | `"./build"` | Output for `bractjs build` |
-| `imageCacheDir` | `string` | `".bract-image-cache"` | Disk cache for optimized images |
-| `sourcemap` | `string` | `"external"` | `"none"` \| `"inline"` \| `"external"` |
-| `minify` | `boolean` | `true` | Minify client bundles |
-| `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
-| `onStart` | `() => void \| Promise<void>` | — | Called once after the server starts listening |
-| `onShutdown` | `() => void \| Promise<void>` | — | Called before process exit on any signal |
-| `onError` | `(err, request?) => void \| Promise<void>` | — | Called on every unexpected error; `request` is `undefined` for process-level exceptions |
+On the server, read env via `Bun.env.*` directly.
 ---
-## CLI
+## 18. Typed routes codegen
-| Command | Description |
-|---------|-------------|
-| `bractjs new <name>` | Scaffold a new app into `<name>/` |
-| `bractjs dev` | Start dev server with HMR on port 3000 |
-| `bractjs build` | Dual server + client build with content-hashed output |
-| `bractjs start` | Serve the production build |
-| `bractjs codegen [app] [out]` | Generate typed route types into `app/route-types.gen.ts` |
-| `bractjs codegen:registry [app]` | Generate `app/_generated/{routes,actions}.ts` (single-binary prep) |
-| `bractjs codegen:manifest [app] [build]` | Snapshot `route-manifest.json` into `app/_generated/manifest.ts` |
-| `bractjs compile [outfile] [entry]` | Full single-binary pipeline (codegen → build → compile) |
+Generate per-route param types and a type-safe URL builder from your route files.
-The CLI is a thin convenience layer. Every command delegates to a public programmatic API — you can call the same functions directly from your own scripts without the CLI.
+```sh
+bractjs codegen                       # ./app → ./app/route-types.gen.ts
+bractjs codegen ./app ./app/types.ts  # explicit paths
+```
----
+Runs automatically during `bractjs build`. The generated file provides:
-## Single-Binary Deployment (`bun build --compile`)
+```ts
+export type AppRoutes = "/" | "/blog/:id" | "/org/:orgId/repo/:repoId";
-BractJS can be packaged as a single executable using Bun's `--compile` flag. Because `bun build --compile` can't trace runtime filesystem scans or dynamic `import(absPath)` calls, BractJS provides a codegen step that materialises every route, layout, and server action into static imports. The compiled binary has zero filesystem dependence at startup.
+export type RouteParams<T extends AppRoutes> =
+  T extends "/blog/:id" ? { id: string } : Record<never, never>;
-### One-shot
+export type TypedLoaderArgs<T extends AppRoutes> = { request: Request; params: RouteParams<T>; context: Record<string, unknown> };
+export type TypedActionArgs<T extends AppRoutes> = TypedLoaderArgs<T> & { formData: FormData };
-```sh
-bractjs compile ./myapp
-# Equivalent to:
-#   bractjs codegen:registry      # writes app/_generated/{routes,actions}.ts
-#   bractjs build                 # writes build/client/* + route-manifest.json
-#   bractjs codegen:manifest      # snapshots manifest → app/_generated/manifest.ts
-#   bun build --compile app/server.ts --outfile ./myapp
+export const routes = {
+  "/": () => "/",
+  "/blog/:id": (p: { id: string }) => `/blog/${p.id}`,
+} as const;
 ```
-### Manual pipeline (custom build step)
+Use them for typed loaders and safe navigation:
-```sh
-bractjs codegen:registry                          # A — scan routes/actions
-bractjs build                                     # B — client + server bundles
-bractjs codegen:manifest                          # C — embed manifest as a TS constant
-bun build --compile app/server.ts \               # D — single binary
-  --asset build/client/ \                         #     (embeds JS/CSS into the binary)
-  --outfile ./myapp
+```ts
+import type { TypedLoaderArgs, RouteParams } from "../route-types.gen.ts";
+import { routes } from "../route-types.gen.ts";
+export async function loader({ params }: TypedLoaderArgs<"/blog/:id">) {
+  return db.post.findById(params.id); // params.id: string
+}
+const { id } = useParams<RouteParams<"/blog/:id">>();
+routes["/blog/:id"]({ id: "123" }); // → "/blog/123"  (typo'd routes won't compile)
 ```
-Asset embedding (`--asset build/client/`) is optional. Without it you ship `myapp` + the `build/client/` folder side-by-side. With it, you get a true single file.
+You can also call `writeRouteTypes(appDir, outPath?)` / `generateRouteTypes(appDir)` programmatically.
-### The `app/server.ts` entry
+---
+## 19. Internationalization utilities
-The scaffold template (`bractjs new`) includes `app/server.ts`:
+BractJS exports **utilities** for locale-prefixed routing. These are helpers you wire up yourself (there is no fully-automatic locale router yet) plus the `useLocale` / `useLocalizedLink` client hooks (§9).
 ```ts
-import { createServer } from "@bractjs/bractjs";
-import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
-import { actionModules } from "./_generated/actions.ts";
-import { manifest } from "./_generated/manifest.ts";
+import { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "@bractjs/bractjs";
+import type { I18nConfig } from "@bractjs/bractjs";
-createServer({
-  port: Number(process.env.PORT ?? 3000),
-  appDir: "./app",
-  publicDir: "./public",
-  manifest,
-  routeFiles,      // skips Bun.Glob route scan
-  moduleRegistry,  // skips dynamic import(absPath) of route modules
-  actionModules,   // skips Bun.Glob + dynamic import for "use server" files
-});
+const i18n: I18nConfig = { locales: ["en", "fr"], defaultLocale: "en" };
+// Add /:locale-prefixed variants alongside the originals.
+const localized = wrapRoutesWithLocale(routeFiles, i18n);
+// Split a locale off a pathname.
+const { locale, strippedPathname } = stripLocale("/fr/about", i18n.locales);
+// → { locale: "fr", strippedPathname: "/about" }
+// Build a locale-aware data path.
+localizedDataPath("/about", "fr"); // → "/fr/about"
 ```
-When all four of `manifest`, `routeFiles`, `moduleRegistry`, and `actionModules` are present, the server boots with **no filesystem reads of `appDir`** — the routing trie, layout chain, server-action registry, and asset manifest all come from the pre-imported modules.
+On the client, read the active locale and build localized links:
-### Custom client builds — required plugins
+```tsx
+const locale = useLocale("en");
+const to = useLocalizedLink("en");
+<Link to={to("/about")} />; // → /en/about
+```
-If you write your own `Bun.build()` call (instead of running `bractjs build`), you MUST apply these plugins or face crashes / secret leaks:
+---
-| Bundle | Plugin | What breaks without it |
-|---|---|---|
-| Server | `useClientStubPlugin` | Server binary crashes when React tries to invoke browser-only hooks/APIs from `"use client"` modules |
-| Client | `createUseServerProxyPlugin(appDir)` | Server-action bodies (DB queries, secrets) ship inside the browser JS |
-| Client | `serverOnlyPlugin` | Imports of `*.server.ts` leak into the client bundle |
-| Client | `clientEnvPlugin(allowedKeys, env)` | Server env vars leak into the browser bundle |
-| Client | `cssModulesPlugin` | `*.module.css` imports don't resolve |
+## 20. Image optimization
-```ts
-import {
-  useClientStubPlugin,
-  createUseServerProxyPlugin,
-  serverOnlyPlugin,
-  clientEnvPlugin,
-  cssModulesPlugin,
-} from "@bractjs/bractjs";
+`<Image>` serves responsive, format-converted images through the built-in `/_image` endpoint. Requires [ImageMagick](https://imagemagick.org) (`magick` or `convert`) — without it, originals are served as-is.
-// Server bundle (target: "bun"):
-plugins: [useClientStubPlugin];
+```tsx
+import { Image } from "@bractjs/bractjs";
-// Client bundle (target: "browser"):
-plugins: [
-  serverOnlyPlugin,
-  createUseServerProxyPlugin("./app"),
-  clientEnvPlugin(["PUBLIC_API_URL"], Bun.env as Record<string, string>),
-  cssModulesPlugin,
-];
+<Image src="/public/hero.jpg" alt="Hero" width={1200} height={600} />
+{/* above-the-fold: eager + fetchpriority=high */}
+<Image src="/public/hero.jpg" alt="Hero" width={1200} priority />
+<Image
+  src="/public/photo.jpg" alt="Photo" width={800}
+  format="avif" quality={70} fit="contain"
+  sizes="(max-width: 640px) 100vw, 50vw"
+/>
 ```
-The `createUseServerProxyPlugin(appDir)` factory exists because server-action IDs are SHA-256 hashes of the appDir-relative path. If the server and client compute different paths (e.g. CI vs prod), every `/_action?id=...` returns 404. Always pass the same `appDir` you pass to `createServer`.
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `src` | `string` | — | Path under `/public/` (required) |
+| `alt` | `string` | — | Required |
+| `width` / `height` | `number` | — | Intrinsic size |
+| `quality` | `number` | `80` | 1–100 |
+| `format` | `"webp" \| "avif" \| "jpeg" \| "png"` | `"webp"` | `ImageFormat` |
+| `fit` | `"cover" \| "contain" \| "fill"` | `"cover"` | `ImageFit` |
+| `priority` | `boolean` | `false` | Disable lazy load, set `fetchpriority=high` |
+| `sizes` | `string` | `"100vw"` | HTML `sizes` |
+Generates a `srcset` across breakpoints (320→1920px). Optimized images are cached in memory (LRU, 200 slots) and on disk (`.bract-image-cache/`, survives restarts), both served `Cache-Control: immutable`. The endpoint validates widths against an allowlist, caps total pixel area, limits concurrency, and kills runaway transforms (DoS hardening).
+`ImageProps`, `ImageFormat`, and `ImageFit` are exported types.
 ---
-## Programmatic API
+## 21. Build & run
+### CLI
+| Command | Description |
+|---------|-------------|
+| `bractjs new <name>` | Scaffold a new app into `<name>/`. |
+| `bractjs dev` | Dev server with HMR (port 3000, HMR ws 3001). |
+| `bractjs build` | Dual server + client build with content-hashed output. |
+| `bractjs start` | Serve the production build. |
+| `bractjs codegen [app] [out]` | Generate `route-types.gen.ts`. |
+| `bractjs codegen:registry [app]` | Generate `app/_generated/{routes,actions}.ts`. |
+| `bractjs codegen:manifest [app] [build]` | Snapshot manifest → `app/_generated/manifest.ts`. |
+| `bractjs compile [outfile] [entry]` | Full single-binary pipeline. |
-All three runtime operations are importable, so BractJS can be embedded in existing servers or custom build scripts without the CLI.
+The CLI is a thin wrapper — every command delegates to a public function, so you can script the same thing.
-### `createDevServer(options?)`
+### Programmatic API
+**`createDevServer(options?)`** — dev server with HMR.
 ```ts
 import { createDevServer } from "@bractjs/bractjs";
 const dev = await createDevServer({
-  port: 3000,    // HTTP port (default: config.port ?? 3000)
-  hmrPort: 3001, // HMR WebSocket port (default: 3001)
+  port: 3000,            // default: config.port ?? 3000
+  hmrPort: 3001,         // HMR websocket
   config: { appDir: "./app", clientEnv: ["PUBLIC_API_URL"] },
-  skipUserConfig: false, // set true to skip loading bractjs.config.ts from cwd
+  skipUserConfig: false, // true → don't read bractjs.config.ts
 });
-// Later — stops the HTTP server and HMR WebSocket server
 dev.stop();
 ```
-### `runBuild(config?)`
+**`runBuild(config?)`** — production build (accepts only build-relevant fields).
 ```ts
 import { runBuild } from "@bractjs/bractjs";
 await runBuild({
   appDir: "./app",
-  buildDir: "./dist",
+  buildDir: "./build",
   minify: true,
-  sourcemap: "external",
+  sourcemap: "external",   // "none" | "linked" | "inline" | "external"
   clientEnv: ["PUBLIC_API_URL"],
+  plugins: [],             // extra Bun plugins
 });
 ```
-`runBuild` only accepts build-relevant fields (`appDir`, `buildDir`, `sourcemap`, `minify`, `clientEnv`, `plugins`). Server-only fields like `port`, `manifest`, and `publicDir` are not accepted — this makes it safe to call from a build script without constructing a full server config.
+**`loadUserConfig()`** — read `bractjs.config.ts` (or `.js`) from cwd, validated.
+```ts
+import { loadUserConfig } from "@bractjs/bractjs";
+const cfg = await loadUserConfig(); // {} if no file; throws on a malformed shape
+```
-### `loadUserConfig()`
+**`createServer(config?)`** — production HTTP server. Returns `{ stop }`.
+```ts
+import { createServer } from "@bractjs/bractjs";
+import lifecycle from "./app/lifecycle.ts";
+const srv = createServer({ port: 3000, buildDir: "./build", ...lifecycle });
+```
+**`buildFetchHandler(config)`** — the adapter-agnostic `(Request) => Promise<Response>` core, if you want to mount BractJS inside another server.
 ```ts
-import { loadUserConfig } from "@bractjs/bractjs";
+import { buildFetchHandler } from "@bractjs/bractjs";
+const handler = buildFetchHandler({ appDir: "./app", manifest });
+Bun.serve({ port: 3000, fetch: handler });
+```
+`renderRoute(options)` (low-level SSR render) and the `RenderOptions`/`ServerManifest`/`BractJSConfig` types are also exported for advanced embedding.
-const cfg = await loadUserConfig();
-// Reads bractjs.config.ts (or .js) from process.cwd()
-// Returns {} if no config file exists
+---
+## 22. Single-binary deployment (`bun build --compile`)
+BractJS compiles to a single executable. Because `bun build --compile` can't trace runtime fs scans or dynamic `import(absPath)`, a codegen step materializes routes, layouts, actions, and the manifest into static imports so the binary boots with **zero filesystem reads of `appDir`**.
+### One-shot
+```sh
+bractjs compile ./myapp
+# = codegen:registry → build → codegen:manifest → bun build --compile app/server.ts
 ```
-### `createServer(config?)` (production)
+### The `app/server.ts` entry
-Already exported. Starts the production HTTP server directly:
+The scaffold includes:
 ```ts
 import { createServer } from "@bractjs/bractjs";
-import lifecycle from "./app/lifecycle.ts";
+import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
+import { actionModules } from "./_generated/actions.ts";
+import { manifest } from "./_generated/manifest.ts";
-createServer({ port: 3000, buildDir: "./build", ...lifecycle });
+createServer({
+  port: Number(process.env.PORT ?? 3000),
+  appDir: "./app",
+  publicDir: "./public",
+  manifest,        // no manifest read from disk
+  routeFiles,      // no Bun.Glob route scan
+  moduleRegistry,  // no dynamic import(absPath)
+  actionModules,   // no scan/import for "use server" files
+});
 ```
----
+When all four are present, the server uses the pre-imported modules for routing, layouts, actions, and assets.
-## App Directory Structure
+### Manual pipeline
+```sh
+bractjs codegen:registry                          # A — scan routes/actions → static imports
+bractjs build                                     # B — client + server bundles + manifest
+bractjs codegen:manifest                          # C — embed manifest as a TS constant
+bun build --compile app/server.ts \               # D — single binary
+  --asset build/client/ --outfile ./myapp
 ```
-my-app/
-├── app/
-│   ├── root.tsx              # required — <html> shell
-│   ├── server.ts             # bun build --compile entrypoint (single-binary build)
-│   ├── lifecycle.ts          # optional — onStart / onShutdown / onError hooks
-│   ├── route-types.gen.ts    # generated by bractjs codegen
-│   ├── _generated/           # generated by bractjs codegen:registry / codegen:manifest
-│   │   ├── routes.ts         # static imports for routes + layouts + root
-│   │   ├── actions.ts        # static imports for "use server" modules
-│   │   └── manifest.ts       # inline ServerManifest constant
-│   ├── actions.ts            # "use server" actions
-│   └── routes/
-│       ├── _index.tsx        # → /
-│       ├── about.tsx         # → /about
-│       ├── blog/
-│       │   ├── layout.tsx    # layout for /blog/*
-│       │   ├── _index.tsx    # → /blog
-│       │   └── [id].tsx      # → /blog/:id
-│       └── docs/
-│           └── [...slug].tsx # → /docs/*
-├── public/
-│   └── favicon.ico
-└── build/                    # generated — do not edit
-    ├── server/
-    ├── client/
-    └── route-manifest.json
-```
-The `_generated/` directory is only required for the single-binary workflow. Regular `bractjs dev` / `bractjs build` / `bractjs start` work without it.
+`--asset build/client/` embeds JS/CSS into the binary (true single file); omit it to ship `myapp` + `build/client/` side by side.
+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).
 ---
-## Architecture
+## 23. Custom adapters
-```
-Request
-  └─ Middleware pipeline
-       └─ /_action  → Server Action registry → fn(...args)
-       └─ /_image   → ImageMagick transform → LRU cache → Response
-       └─ Route trie (static > param > catch-all)
-            └─ Layout chain (root → layout → route)
-                 └─ Parallel loaders (Promise.all)
-                      └─ renderToReadableStream → streaming Response
-```
+The server core is adapter-agnostic. The default is `BunAdapter` (wraps `Bun.serve`); supply your own via `createServer({ adapter })`.
-Client:
-```
-hydrateRoot(document)
-  └─ ClientRouter (RouterContext + NavigationContext)
-       └─ Outlet → React.lazy route chunk
-            └─ useLoaderData / useParams / useNavigation / …
-```
+```ts
+import type { BractAdapter } from "@bractjs/bractjs";
+import { BunAdapter } from "@bractjs/bractjs";
-Build pipeline (`bractjs build`):
-```
-1. codegen        → app/route-types.gen.ts
-2. server bundle  → Bun.build (target: bun)   + useClientStubPlugin
-3. client bundle  → Bun.build (target: browser, splitting) + createUseServerProxyPlugin(appDir)
-4. content-hash   → rename outputs, write route-manifest.json
+// BractAdapter: { fetch(req): Promise<Response>; listen?(port): void }
 ```
-Single-binary pipeline (`bractjs compile`):
-```
-A. registry codegen → app/_generated/{routes,actions}.ts (static imports)
-B. dual build       → build/server/, build/client/, route-manifest.json
-C. manifest codegen → app/_generated/manifest.ts (inline constant)
-D. bun build        → single executable with no runtime fs scans
-   --compile app/server.ts [--asset build/client/]
+**Cloudflare Workers:**
+```ts
+import { buildFetchHandler, makeCloudflareHandler } from "@bractjs/bractjs";
+const handler = buildFetchHandler({ appDir: "./app", manifest });
+export default makeCloudflareHandler(handler);
+// or createCloudflareAdapter(handler) for the BractAdapter-compatible form
 ```
 ---
-## Package Structure
+## 24. Build plugins
+If you write your own `Bun.build()` (instead of `bractjs build`), you **must** apply these or face crashes / secret leaks. All are exported.
+| Bundle | Plugin | Without it |
+|---|---|---|
+| Server | `useClientStubPlugin` | Server crashes calling browser-only hooks from `"use client"` modules. |
+| Client | `createUseServerProxyPlugin(appDir)` | Server-action bodies (DB code, secrets) ship in the browser JS. |
+| Client | `serverModuleStubPlugin` | `*.server.ts` source (DB drivers, secrets) leaks into the client bundle. |
+| Client | `clientEnvPlugin(allowedKeys, env)` | Server env vars leak into the browser bundle. |
+| Client | `cssModulesPlugin` | `*.module.css` imports don't resolve. |
+```ts
+import {
+  useClientStubPlugin, createUseServerProxyPlugin,
+  serverModuleStubPlugin, clientEnvPlugin, cssModulesPlugin,
+} from "@bractjs/bractjs";
+// Server bundle (target: "bun"):
+plugins: [useClientStubPlugin];
+// Client bundle (target: "browser"):
+plugins: [
+  serverModuleStubPlugin,
+  createUseServerProxyPlugin("./app"),               // same appDir as createServer!
+  clientEnvPlugin(["PUBLIC_API_URL"], Bun.env as Record<string, string>),
+  cssModulesPlugin,
+];
 ```
-bractjs/
-├── src/
-│   ├── server/      # SSR, routing, loaders, actions, sessions, action-registry
-│   ├── client/      # hydrateRoot, contexts, hooks, Link/Form/Image components
-│   ├── build/       # Bun.build orchestration, manifest, hashing, directives
-│   ├── codegen/     # route-types.gen.ts + module-registry codegen (_generated/*)
-│   ├── image/       # /_image handler, ImageMagick optimizer, LRU cache
-│   ├── dev/         # watcher, HMR server + client, error overlay
-│   ├── shared/      # types, errors, deferred, context
-│   └── middleware/  # requestLogger, cors, authGuard
-├── bin/cli.ts
-├── types/           # TypeScript declaration files
-└── templates/
-    └── new-app/     # scaffold template
-```
+> Always pass the **same `appDir`** to `createUseServerProxyPlugin` that you pass to `createServer` — action IDs hash the appDir-relative path, so a mismatch makes every `/_action` return 404. `transformCssModule(filePath)` is exported for custom CSS pipelines; `useServerProxyPlugin` is the legacy absolute-path variant. `serverModuleStubPlugin` stubs `*.server.ts` exports so a route can import a server module inside its loader/action without leaking source; `serverOnlyPlugin` is the stricter predecessor that hard-fails such imports instead (still exported for opt-in use).
 ---
-## Why BractJS
+## 25. Configuration reference
-- **Bun-native** — `Bun.serve`, `Bun.build`, `Bun.file`, `Bun.Glob`, `Bun.watch`. No Node.js.
-- **Zero framework deps** — only peer dependencies are `react` and `react-dom`.
-- **Streaming SSR** — `renderToReadableStream()` with `defer()` for slow data.
-- **File-based routing** — drop a file in `app/routes/`, it's a route.
-- **Full-stack** — loaders, actions, sessions, server actions, and middleware in one package.
-- **Typed routes** — codegen produces per-route param types and a type-safe route builder.
+All fields optional. Put them in `bractjs.config.ts` (default export) or pass to `createServer` / `createDevServer` / `runBuild`.
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | `number` | `3000` | TCP port |
+| `appDir` | `string` | `"./app"` | Contains `routes/` and `root.tsx` |
+| `publicDir` | `string` | `"./public"` | Static assets (served no-cache) |
+| `buildDir` | `string` | `"./build"` | Build output |
+| `imageCacheDir` | `string` | `".bract-image-cache"` | Optimized-image disk cache |
+| `sourcemap` | `string` | `"external"` | `"none" \| "linked" \| "inline" \| "external"` |
+| `minify` | `boolean` | `true` | Minify client bundles |
+| `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
+| `plugins` | `BunPlugin[]` | `[]` | Extra client-build plugins |
+| `adapter` | `BractAdapter` | `BunAdapter` | Custom server adapter |
+| `i18n` | `I18nConfig` | — | Locale config consumed by the i18n utilities |
+| `onStart` / `onShutdown` / `onError` | hooks | — | Lifecycle (§16) |
+`loadUserConfig()` validates these shapes and throws a clear error on an obvious mistake (e.g. a string `port`).
 ---
-## Status
+## 26. Full export index
+Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
+**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `BunAdapter`, `defineLifecycle`
+**Errors:** `BractJSError`, `HttpError`, `isRedirect`, `isHttpError`, `isBractJSError`
+**Streaming:** `defer`, `Deferred`, `isDeferred`, `Await`
+**Context:** `BractJSContext`, `BractJSProvider`, `useBractJSContext`
+**Middleware:** `pipeline`, `MiddlewarePipeline`, `requestLogger`, `cors`, `authGuard`, `csp`, `getCspNonce`, `CSP_NONCE_KEY`
+**Sessions:** `createCookieSession`
+**Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`
-**v0.1.21.** All core phases shipped:
+**Hooks:** `useLoaderData`, `useActionData`, `useParams`, `useNavigation`, `useFetcher`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
-- File-based routing with trie matcher and layout chains
-- Streaming SSR (`renderToReadableStream`) with `defer()` and `<Await>`
-- Client hydration, soft navigation, `popstate`, prefetch
-- HMR with module-level swap (no full reload)
-- Cookie sessions with HMAC-SHA256 and secret rotation
-- Middleware pipeline with `requestLogger`, `cors`, `authGuard`
-- Production build with content-hashed assets and code splitting
-- `<Image>` with on-demand ImageMagick optimization and LRU cache
-- Typed routes codegen (`AppRoutes`, `RouteParams<T>`, `TypedLoaderArgs<T>`, `routes` builder)
-- `"use server"` / `"use client"` directive system with `/_action` endpoint
-- **Programmatic API** — `createDevServer`, `runBuild`, `loadUserConfig` importable without the CLI
-- **Native `bun build --compile` support** — module-registry codegen produces single-binary deployables; build plugins exported from the public API; action IDs use relative paths for cross-machine stability
+**i18n:** `wrapRoutesWithLocale`, `stripLocale`, `localizedDataPath`
-Remaining on the roadmap: streaming `useFetcher()` (full implementation).
+**Client RPC:** `createClient`
+**Build / programmatic:** `createDevServer`, `runBuild`, `loadUserConfig`
+**Codegen:** `writeModuleRegistries`, `writeManifestModule`, `generateRouteRegistry`, `generateActionRegistry`, `generateManifestModule`
+**Build plugins:** `useClientStubPlugin`, `createUseServerProxyPlugin`, `useServerProxyPlugin`, `serverModuleStubPlugin`, `serverOnlyPlugin`, `clientEnvPlugin`, `cssModulesPlugin`, `transformCssModule`
+**Adapters:** `createCloudflareAdapter`, `makeCloudflareHandler`
+**Types:** `LoaderArgs`, `ActionArgs`, `MetaArgs`, `MetaDescriptor`, `LoaderFunction`, `ActionFunction`, `MetaFunction`, `RouteModule`, `RouteDefinition`, `RouteFile`, `Segment`, `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`, `I18nConfig`, `DevServerOptions`, `DevServer`, `BuildConfig`, `CodegenResult`, `ModuleRegistry`, `BractJSContextValue`, `RouteManifest`
 ---
+## Changelog
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+---
+## Why BractJS
+- **Bun-native** — `Bun.serve`, `Bun.build`, `Bun.file`, `Bun.Glob`, `Bun.watch`. No Node.js.
+- **Zero framework deps** — only peers are `react` and `react-dom`.
+- **Streaming SSR** — `renderToReadableStream()` with `defer()` and `<Await>`.
+- **File-based routing** — drop a file in `app/routes/`.
+- **Full-stack** — loaders, actions, sessions, server actions, typed API routes, middleware.
+- **Typed routes** — codegen produces per-route params and a type-safe URL builder.
+- **Single-binary** — `bun build --compile` to one executable.
 ## License
 MIT