@bractjs/bractjs 0.1.26 → 0.1.28

package/README.md

@@ -34,7 +34,7 @@ This README is a **step-by-step guide to every function and feature** BractJS ex
 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)
+18. [Typed routes](#18-typed-routes)
 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)
@@ -175,14 +175,18 @@ import type { LoaderArgs, ActionArgs, MetaArgs } from "@bractjs/bractjs";
 import { redirect, json, HttpError } from "@bractjs/bractjs";
 
 // 1) loader — runs on every GET. Return value → useLoaderData().
-export async function loader({ request, params, context }: LoaderArgs) {
+//    `search` is the validated output of searchSchema (below), or the raw
+//    string record when the route has no schema.
+export async function loader({ request, params, context, search }: LoaderArgs) {
   const post = await db.post.findById(params.id);
   if (!post) throw new HttpError(404, "Not found"); // → 404 page
   return { post };
 }
 export type LoaderData = Awaited<ReturnType<typeof loader>>;
 
-// 2) action — runs on POST / PUT / DELETE / PATCH.
+// 2) action — runs on POST / PUT / DELETE / PATCH. For one route handling
+//    several buttons, compose it from `defineActions` (§5a) instead of a
+//    hand-rolled `intent` switch.
 export async function action({ request, params, context, formData }: ActionArgs) {
   await db.post.update(params.id, { title: formData.get("title") as string });
   return redirect("/blog");
@@ -210,7 +214,35 @@ export function ErrorBoundary({ error }: { error: unknown }) {
   return <p>Something broke: {error instanceof Error ? error.message : String(error)}</p>;
 }
 
-// 6) default — the page component (required for a renderable route).
+// 6) searchSchema — validate/coerce search params BEFORE loaders run (Zod,
+//    Valibot, or anything with parse/safeParse). Failure → 400; use
+//    .catch()/.default() per field for URLs that must tolerate junk.
+//    Loaders receive the OUTPUT via `search`; the client reads it with
+//    useSearch() — numbers stay numbers. (Typed end-to-end after codegen, §18.)
+export const searchSchema = z.object({
+  page: z.coerce.number().int().positive().catch(1),
+  q: z.string().optional(),
+});
+
+// 7) shouldRevalidate — veto automatic data refetches (the SWR background
+//    refetch, and the revalidation after <Form>/fetcher mutations).
+export function shouldRevalidate({ currentUrl, nextUrl, formMethod, defaultShouldRevalidate }) {
+  if (formMethod === "DELETE") return true;     // always refetch after deletes
+  return defaultShouldRevalidate;
+}
+
+// 8) ssr + Fallback — selective SSR (see also §21 for app-wide SPA mode):
+//    true (default)  full document SSR
+//    "data-only"     loaders run on the server; component renders client-only
+//    false           loader + component skipped during document SSR; the
+//                    client fetches /_data after hydration.
+//    beforeLoad ALWAYS runs on the server — ssr:false is not an auth bypass.
+export const ssr = "data-only";
+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).
 export default function BlogPost() {
   const { post } = useLoaderData<LoaderData>();
   return <article><h1>{post.title}</h1></article>;
@@ -220,7 +252,7 @@ export default function BlogPost() {
 **Execution order for a request:**
 
 ```
-beforeLoad → (action, if mutating method) → loaders (root + layouts + route, in parallel) → render
+searchSchema → 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`).
@@ -228,6 +260,44 @@ beforeLoad → (action, if mutating method) → loaders (root + layouts + route,
 
 > **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.
 
+### Less boilerplate
+
+**Infer loader data — `useLoaderData<typeof loader>()`.** Pass the loader function type and the data type is inferred from its return (no `LoaderData` alias to maintain). The `Response` redirect branch is excluded; `Deferred` fields (from `defer()`, §8) are preserved for `<Await>`. Same for `useActionData<typeof action>()`.
+```tsx
+export async function loader() { return { post: await db.post.find() }; }
+export default function Post() {
+  const { post } = useLoaderData<typeof loader>();   // typed — no hand-written type
+}
+```
+
+**Type search params on the args — `LoaderArgs<T>`.** Parameterize to drop the cast (the schema's output type):
+```tsx
+export async function loader({ search }: LoaderArgs<{ page: number }>) {
+  return db.posts({ page: search.page });            // search.page is a number
+}
+// After codegen (§18), `LoaderArgsFor<"/posts">` types params + context + search from the route.
+```
+
+### `defineActions` — multi-button forms without an `intent` switch
+
+A route action that handles several buttons usually devolves into `if (intent === …)`. `defineActions` composes it from one handler per intent, and `<Form intent="…">` (§10) renders the matching hidden input. An unknown/missing intent returns a 400 automatically (dev lists the known intents).
+```tsx
+import { defineActions, safeValidate, formText } from "@bractjs/bractjs";
+
+export const action = defineActions({
+  add:    async ({ formData }) => {
+    const r = await safeValidate(TitleSchema, formData);   // §13
+    if (!r.ok) return { error: r.firstError };
+    addTodo(r.data.title); return {};
+  },
+  toggle: ({ formData }) => { toggleTodo(formText(formData, "id")); return {}; },
+  delete: ({ formData }) => { deleteTodo(formText(formData, "id")); return {}; },
+});
+```
+```tsx
+<Form method="post" intent="toggle"><input type="hidden" name="id" value={id} /><button>Toggle</button></Form>
+```
+
 ---
 
 ## 6. Response helpers
@@ -317,22 +387,22 @@ export async function loader({ params }: LoaderArgs) {
 }
 
 export default function BlogPost() {
-  const { post, comments } = useLoaderData<LoaderData>();
+  // useLoaderData<typeof loader>() infers the shape — `comments` stays a
+  // Deferred<Comment[]>, which <Await> accepts directly.
+  const { post, comments } = useLoaderData<typeof loader>();
   return (
     <article>
       <h1>{post.title}</h1>
-      <Suspense fallback={<p>Loading comments…</p>}>
-        <Await resolve={comments}>
-          {(c) => <CommentList comments={c} />}
-        </Await>
-      </Suspense>
+      <Await resolve={comments} fallback={<p>Loading comments…</p>}>
+        {(c) => <CommentList comments={c} />}
+      </Await>
     </article>
   );
 }
 ```
 
-### `<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.
+### `<Await resolve={promise | Deferred} fallback={…}>{(data) => …}</Await>`
+Unwraps a promise (or a `Deferred` field from a `defer()` loader) 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.
 
 ---
 
@@ -341,45 +411,93 @@ Unwraps a promise with React 19's `use()` inside its own `<Suspense>`. `isDeferr
 All hooks are SSR-safe (they return sensible values during SSR) and imported from `@bractjs/bractjs`.
 
 ### `useLoaderData<T>()` → `T`
-The current route's loader return value.
+The current route's loader return value. **Pass the loader function type** to infer it (`Response` branch excluded, `Deferred` fields preserved) — no hand-written type to keep in sync. An explicit object type still works.
 ```ts
-const { post } = useLoaderData<LoaderData>();
+const { post } = useLoaderData<typeof loader>();   // inferred from loader()
+const { post } = useLoaderData<LoaderData>();       // or an explicit type
 ```
 
 ### `useActionData<T>()` → `T | null`
-The most recent action return value (null until an action runs).
+The most recent action return value (null until an action runs). Like `useLoaderData`, accepts the action function type.
 ```ts
-const result = useActionData<{ error?: string }>();
+const result = useActionData<typeof action>();
 ```
 
 ### `useParams<T>()` → `T`
-URL dynamic params. Pass a generic for typed params.
+URL dynamic params. Pass the **route pattern** as a generic to type the result against your codegen'd routes (see §18); an object shape also works.
+```ts
+const { id } = useParams<"/blog/:id">();        // { id: string } — typed from routes
+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).
+
+### `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
-const { id } = useParams<{ id: string }>();
+const location = useLocation();
+const isActive = location.pathname.startsWith("/blog");
 ```
 
 ### `useNavigation()` → `{ state }`
-`"idle" | "loading" | "submitting"`.
+`"idle" | "loading" | "submitting"`. Form/`submit()` mutations walk `"submitting"` → `"loading"` (revalidation) → `"idle"`.
 ```ts
 const { state } = useNavigation();
 if (state === "loading") return <Spinner />;
 ```
 
+### `useNavigate()` → `(to, { params?, search?, replace?, state? }) => Promise<void>`
+Imperative soft navigation — the counterpart to `<Link>`. `to` autocompletes your routes (after codegen, §18); `params` and `search` are typed per route; any string is still accepted.
+```ts
+const navigate = useNavigate();
+await navigate("/blog/:id", { params: { id: "42" } });     // typed
+await navigate("/posts", { search: { page: 2 } });          // typed search → /posts?page=2
+await navigate("/login", { replace: true });                // replaceState, no history entry
+await navigate("/wizard/2", { state: { from: "step1" } });  // read via useLocation().state
+```
+
+### `useRevalidator()` → `{ revalidate, state }`
+Manually re-run the current route's loaders — for "Refresh" buttons, polling, or after out-of-band changes (e.g. a WebSocket event). Respects the route's `shouldRevalidate`. `state` is `"idle" | "loading"` and tracks only revalidation (navigations are `useNavigation()`).
+```ts
+const { revalidate, state } = useRevalidator();
+<button onClick={() => void revalidate()} disabled={state === "loading"}>Refresh</button>
+```
+
+### `useSearch()` / `useSetSearch()` — typed, validated search params
+`useSearch` returns the route's **validated** search object (the `searchSchema` output — numbers are numbers, defaults applied). Validation runs once on the server; the client never re-runs the schema. `useSetSearch` merges a patch, writes the URL, and soft-navigates so loaders re-run. Set a key to `undefined` to delete it.
+```ts
+const search = useSearch<"/posts">();              // { page: number; q?: string }
+const setSearch = useSetSearch<"/posts">();
+setSearch({ page: search.page + 1 });              // patch → /posts?page=2&q=…
+setSearch((prev) => ({ q: undefined }), { replace: true });  // delete + replaceState
+```
+
 ### `useSearchParams<T>()` → `{ searchParams, getParam, setSearchParams }`
-Read/write URL query params; writing triggers a soft-nav loader re-run.
+The low-level escape hatch: raw string `URLSearchParams` read/write; writing triggers a soft-nav loader re-run. Prefer `useSearch`/`useSetSearch` (above) when the route has a `searchSchema`.
 ```ts
-const { searchParams, getParam, setSearchParams } = useSearchParams<{ q: string }>();
-const q = getParam("q");                       // string | null
-setSearchParams({ q: "bun" });                 // replace all params
+const { searchParams, getParam, setSearchParams } = useSearchParams<"/blog/:id">();
+const q = getParam("q");                        // string | null
+setSearchParams({ q: "bun" });                  // replace all params
 setSearchParams((prev) => { prev.set("page", "2"); return prev; }); // update
 ```
 
-### `useFetcher()` → `{ data, state, load, submit }`
-Background fetch without navigating.
+### `useFetcher({ key? })` → `{ data, state, formData, formMethod, load, submit, Form, key }`
+Background fetch/mutation without navigating. After a `submit`, the active route's loaders revalidate automatically (gated by `shouldRevalidate`). `formData`/`formMethod` are set from the moment `submit` is called — render them for **optimistic UI**. A `key` gives the fetcher a stable identity shared across components and surviving remounts; unkeyed fetchers are component-bound.
 ```ts
-const fetcher = useFetcher();
+const fetcher = useFetcher({ key: `delete-${id}` });
 await fetcher.load("/products?q=bun");                       // GET loader data
 await fetcher.submit("/cart", { method: "post", body: { id: "1" } });
+const optimisticTitle = fetcher.formData?.get("title");      // while submitting
+<fetcher.Form method="post" action="/cart">…</fetcher.Form>  {/* scoped form, no navigation */}
+```
+
+### `useFetchers()` → `FetcherEntry[]`
+Every active fetcher — the cross-component view for optimistic UI (e.g. dim each table row whose keyed delete fetcher is in flight elsewhere in the tree).
+```ts
+const deleting = new Set(
+  useFetchers()
+    .filter((f) => f.state === "submitting" && f.key.startsWith("delete-"))
+    .map((f) => f.key.slice("delete-".length)),
+);
 ```
 
 ### `useFetcher<T>({ stream: true })` → `{ connect }`
@@ -415,15 +533,37 @@ export default function BlogLayout() {
 }
 ```
 
-### `<Link to prefetch? viewTransition?>`
-Soft-navigates without a full reload.
+### `<Link to params? search? prefetch? replace? viewTransition?>`
+Soft-navigates without a full reload. After codegen (§18), `to` autocompletes your routes; for a dynamic route pass typed `params`, and `search` is typed by the target's `searchSchema`. Building the URL yourself still works, so existing links need no changes.
 ```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 */}
+<Link to="/blog/:id" params={{ id: "42" }}>Read</Link>  {/* typed route + params */}
+<Link to={`/blog/${id}`}>Read</Link>                    {/* built string — also fine */}
+<Link to="/posts" search={{ page: 2 }}>Page 2</Link>    {/* typed search params */}
+<Link to="/about" prefetch="intent">About</Link>        {/* preload on hover/focus intent */}
+<Link to="/gallery" viewTransition>Gallery</Link>       {/* use View Transitions API */}
 ```
 Modifier-clicks (ctrl/cmd/shift/alt) fall back to native browser navigation.
 
+**Prefetch modes** — prefetching warms the route chunk (`modulepreload`) *and* the loader cache, so the click commits instantly (prefetched data stays fresh ≥ 30s; concurrent data prefetches are capped at 6 so long lists can't stampede the server):
+
+| mode | when |
+|---|---|
+| `"none"` (default) | never |
+| `"intent"` | hover **or focus**, after a 100 ms delay (canceled on fly-by) — best default |
+| `"hover"` | immediately on mouseenter (legacy alias) |
+| `"viewport"` | when the link scrolls into view (one shared IntersectionObserver) — for lists |
+| `"render"` | as soon as the link mounts |
+
+### `<ScrollRestoration getKey? storageKey?>`
+Restores the window scroll position on back/forward (and reload), scrolls to top — or to the `#hash` element — on new navigations. Render it **once** in `app/root.tsx`, next to `<Scripts />`. Positions persist in `sessionStorage`. Pass `getKey={(location) => location.pathname}` to share one position across every visit to the same path.
+```tsx
+<body>
+  <Outlet />
+  <ScrollRestoration />
+  <Scripts />
+</body>
+```
+
 ### `<Form method action?>`
 Fetch-based submission that re-runs the current route's loader after the action.
 ```tsx
@@ -561,6 +701,27 @@ export async function action({ formData }: ActionArgs) {
 - 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.
 
+### `safeValidate` — validate without try/catch (recommended for inline form errors)
+
+Returns a result instead of throwing — the clean idiom when you want to render field errors rather than a 400 page. `firstError` is the first field message.
+```ts
+import { safeValidate } from "@bractjs/bractjs";
+
+export const action = defineActions({
+  create: async ({ formData }) => {
+    const r = await safeValidate(Schema, formData);
+    if (!r.ok) return { error: r.firstError, fieldErrors: r.fieldErrors };
+    await db.post.create(r.data);   // r.data is typed + coerced
+    return redirect("/blog");
+  },
+});
+```
+If you prefer to keep calling `validate()` and catching: `isValidationResponse(err)` narrows the thrown 400, and `readValidationError(res)` parses it into `{ fieldErrors, firstError }`.
+
+### FormData helpers
+
+`formText(formData, key)` returns a string (`""` for missing or File values) — no more `String(formData.get(k) ?? "")`. `formValues(formData, keys?)` collects string fields into an object (all, or a named subset).
+
 ---
 
 ## 14. Middleware
@@ -602,10 +763,13 @@ pipeline.use(authGuard({ session, required: true })); // 401 if no session.user
 pipeline.use(csp({
   directives: { "img-src": "'self' data: https://cdn.example", "frame-ancestors": "'none'" },
   reportOnly: false, // true → Content-Security-Policy-Report-Only
+  strict: false,     // true → drop 'unsafe-inline' from style-src (see below)
 }));
 ```
 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.
+
 ### Custom middleware
 
 ```ts
@@ -738,48 +902,55 @@ On the server, read env via `Bun.env.*` directly.
 
 ---
 
-## 18. Typed routes codegen
+## 18. Typed routes
 
-Generate per-route param types and a type-safe URL builder from your route files.
+Generate type-safe routing from your route files — one command wires `<Link>`, `useNavigate`, `useParams`, and `useSearchParams` to your actual routes.
 
 ```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:
+**You rarely run this by hand.** `bractjs new` generates it on scaffold, `bractjs dev` regenerates it on boot and whenever you add/remove/rename a route file, and `bractjs build` runs it too. The output is deterministic (route-sorted) and carries a `// bractjs:routes <hash>` fingerprint, so re-runs that change nothing don't rewrite the file (no editor reload loops); on boot the dev server prints precisely what drifted. Make sure the generated file is part of your TypeScript program (it is, if your `tsconfig.json` `include`s `app/`). It augments BractJS's `Register` interface, after which the runtime components and hooks become type-safe — **no per-route imports needed**:
 
-```ts
-export type AppRoutes = "/" | "/blog/:id" | "/org/:orgId/repo/:repoId";
-
-export type RouteParams<T extends AppRoutes> =
-  T extends "/blog/:id" ? { id: string } : Record<never, never>;
+```tsx
+<Link to="/blog/:id" params={{ id }} />     // ✅ "/blog/:id" autocompletes; params typed
+<Link to="/blgo/:id" params={{ id }} />     // ❌ typo'd route — compile error
+<Link to="/blog/:id" params={{ x: id }} />  // ❌ wrong param key — compile error
 
-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 };
+const navigate = useNavigate();
+navigate("/blog/:id", { params: { id } });  // ✅ same typing as <Link>
 
-export const routes = {
-  "/": () => "/",
-  "/blog/:id": (p: { id: string }) => `/blog/${p.id}`,
-} as const;
+const { id } = useParams<"/blog/:id">();     // id: string
 ```
 
-Use them for typed loaders and safe navigation:
+Building the URL yourself (`<Link to={`/blog/${id}`}>`) still type-checks, so adopting codegen never breaks existing links.
+
+The generated file also exports types/helpers for typed loaders and explicit URL building:
 
 ```ts
-import type { TypedLoaderArgs, RouteParams } from "../route-types.gen.ts";
+import type { TypedLoaderArgs } 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
+  return db.post.findById(params.id);          // params.id: string
 }
+routes["/blog/:id"]({ id: "123" });            // → "/blog/123"  (typo'd routes won't compile)
+```
+
+**Type a route's search params or context** by augmenting the package interfaces — `SearchParams<T>` / `Context<T>` and `useSearchParams<T>()` pick it up:
 
-const { id } = useParams<RouteParams<"/blog/:id">>();
-routes["/blog/:id"]({ id: "123" }); // → "/blog/123"  (typo'd routes won't compile)
+```ts
+declare module "@bractjs/bractjs" {
+  interface RouteSearchParamsMap { "/blog": { page: string; sort: string } }
+  interface RouteContextMap { "/admin": { user: { id: string; role: "admin" } } }
+}
 ```
 
 You can also call `writeRouteTypes(appDir, outPath?)` / `generateRouteTypes(appDir)` programmatically.
 
+> **Heads up:** earlier versions documented `useParams<RouteParams<"/blog/:id">>()` and untyped `<Link to={string}>`. The route-literal form (`useParams<"/blog/:id">()`) and typed `<Link>`/`useNavigate` are the current API; the old forms still compile.
+
 ---
 
 ## 19. Internationalization utilities
@@ -917,6 +1088,37 @@ Bun.serve({ port: 3000, fetch: handler });
 
 `renderRoute(options)` (low-level SSR render) and the `RenderOptions`/`ServerManifest`/`BractJSConfig` types are also exported for advanced embedding.
 
+### Rendering modes
+
+Three levels of SSR control, all opt-in:
+
+**Per-route selective SSR** — `export const ssr = false | "data-only"` plus a `Fallback` component on any route (§5 item 8). The document SSRs the Fallback; the client swaps in the real component after hydration. `beforeLoad` always runs server-side.
+
+**App-wide SPA mode** — `ssr: false` in `bractjs.config.ts`:
+
+```ts
+// bractjs.config.ts
+export default {
+  ssr: false,   // every document GET serves one static shell
+};
+```
+
+SPA mode means **"no document SSR", not "no server"**: the Bun server keeps serving `/_data` (loaders), `/_action`/mutations (CSRF gate intact), `/_image`, API routes, and static assets. `bractjs build` emits the shell at `build/client/__spa.html`; in dev it renders on the fly so `root.tsx` edits show up. Constraints: the root component renders without loader data and with a `/` location, so keep location/loader-dependent markup out of `root.tsx`; route-level `meta()` only applies after hydration (no SEO for route content).
+
+**Build-time prerendering (SSG)** — `prerender` in `bractjs.config.ts`:
+
+```ts
+// bractjs.config.ts
+export default {
+  prerender: ["/", "/about", "/blog/intro"],
+  // or resolve dynamically: prerender: async () => (await db.posts()).map(p => `/blog/${p.slug}`),
+};
+```
+
+`bractjs build` runs the real loaders in-process (anything they need — DB, env — must be available at build time), writing each path's HTML **and** its `/_data` payload (used by client navigations *into* a prerendered page) under `build/client/_prerender/`. In production, clean URLs are served from these files before dynamic SSR; **a query string opts the request back into SSR** (the file was rendered without one). Paths must be concrete — expand `"/blog/:slug"` yourself; the build fails on patterns. `runPrerender(options)` is exported for custom pipelines.
+
+Deployment notes: with `bun build --compile`, ship `build/client/` (including `_prerender/`) alongside the binary — or pass it via `--asset`. On Cloudflare, upload `build/client/` as static assets so the platform serves prerendered files before the worker runs.
+
 ---
 
 ## 22. Single-binary deployment (`bun build --compile`)
@@ -1028,11 +1230,17 @@ plugins: [
 
 ## 25. Configuration reference
 
-All fields optional. Put them in `bractjs.config.ts` (default export) or pass to `createServer` / `createDevServer` / `runBuild`.
+All fields optional. Wrap the default export in `defineConfig()` for autocomplete + type-checking (it's a no-op identity helper), or pass these to `createServer` / `createDevServer` / `runBuild`.
+
+```ts
+import { defineConfig } from "@bractjs/bractjs";
+export default defineConfig({ port: 3000, clientEnv: ["PUBLIC_API_URL"] });
+```
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
 | `port` | `number` | `3000` | TCP port |
+| `hmrPort` | `number` | `3001` | Dev HMR WebSocket port (`bractjs dev` only) |
 | `appDir` | `string` | `"./app"` | Contains `routes/` and `root.tsx` |
 | `publicDir` | `string` | `"./public"` | Static assets (served no-cache) |
 | `buildDir` | `string` | `"./build"` | Build output |
@@ -1043,6 +1251,8 @@ All fields optional. Put them in `bractjs.config.ts` (default export) or pass to
 | `plugins` | `BunPlugin[]` | `[]` | Extra client-build plugins |
 | `adapter` | `BractAdapter` | `BunAdapter` | Custom server adapter |
 | `i18n` | `I18nConfig` | — | Locale config consumed by the i18n utilities |
+| `ssr` | `boolean` | `true` | `false` → SPA mode: static shell for every document GET (§21) |
+| `prerender` | `string[] \| () => paths` | — | Paths to prerender at build time (§21) |
 | `onStart` / `onShutdown` / `onError` | hooks | — | Lifecycle (§16) |
 
 `loadUserConfig()` validates these shapes and throws a clear error on an obvious mistake (e.g. a string `port`).
@@ -1053,7 +1263,7 @@ All fields optional. Put them in `bractjs.config.ts` (default export) or pass to
 
 Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
 
-**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `BunAdapter`, `defineLifecycle`
+**Server / runtime:** `createServer`, `buildFetchHandler`, `renderRoute`, `redirect`, `json`, `error`, `defineContext`, `route`, `validate`, `safeValidate`, `isValidationResponse`, `readValidationError`, `validateSearch`, `searchParamsToObject`, `formText`, `formValues`, `defineActions`, `BunAdapter`, `defineLifecycle`, `renderSpaShell`
 
 **Errors:** `BractJSError`, `HttpError`, `isRedirect`, `isHttpError`, `isBractJSError`
 
@@ -1065,15 +1275,17 @@ Everything importable from `@bractjs/bractjs` ([src/index.ts](src/index.ts)):
 
 **Sessions:** `createCookieSession`
 
-**Components:** `Outlet`, `Link`, `Form`, `Scripts`, `LiveReload`, `Await`, `Image`
+**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`, `useParams`, `useNavigation`, `useFetcher`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
+**Search serialization:** `serializeSearch`
 
 **i18n:** `wrapRoutesWithLocale`, `stripLocale`, `localizedDataPath`
 
 **Client RPC:** `createClient`
 
-**Build / programmatic:** `createDevServer`, `runBuild`, `loadUserConfig`
+**Build / programmatic:** `createDevServer`, `runBuild`, `loadUserConfig`, `defineConfig`, `runPrerender`
 
 **Codegen:** `writeModuleRegistries`, `writeManifestModule`, `generateRouteRegistry`, `generateActionRegistry`, `generateManifestModule`
 
@@ -1081,7 +1293,20 @@ 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`, `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`
+**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`
+
+---
+
+## 27. Security model
+
+BractJS ships secure defaults, but a few behaviors are worth understanding so you don't accidentally widen your attack surface.
+
+- **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`.
+- **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.
 
 ---
 
@@ -1098,7 +1323,7 @@ See [CHANGELOG.md](CHANGELOG.md) for release history.
 - **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.
+- **Typed routes** — codegen wires `<Link>`, `useNavigate`, and `useParams` to your routes (autocompleted paths, typed params), plus a type-safe URL builder.
 - **Single-binary** — `bun build --compile` to one executable.
 
 ## License

package/bin/cli.ts

@@ -43,6 +43,10 @@ async function scaffoldNew(appName: string): Promise<void> {
   try {
     const { writeModuleRegistries } = await import("../src/codegen/module-registry.ts");
     await writeModuleRegistries(join(appDir, "app"));
+    // Generate typed routes so the scaffold has working <Link>/useParams typing
+    // out of the box (no manual `bractjs codegen` step before first dev run).
+    const { writeRouteTypes } = await import("../src/codegen/route-codegen.ts");
+    await writeRouteTypes(join(appDir, "app"));
     // Manifest stub — overwritten by `bractjs codegen:manifest` after a build
     const stubManifest = [
       "// Stub manifest — replaced by `bractjs codegen:manifest` after running",
@@ -101,6 +105,16 @@ switch (command) {
     const { loadUserConfig } = await import("../src/config/load.ts");
     const userCfg = await loadUserConfig();
     await runBuild({ appDir: "./app", buildDir: "./build", ...userCfg });
+    if (userCfg.prerender) {
+      const { runPrerender } = await import("../src/build/prerender.ts");
+      const { written } = await runPrerender({
+        prerender: userCfg.prerender,
+        appDir: userCfg.appDir ?? "./app",
+        publicDir: userCfg.publicDir,
+        buildDir: userCfg.buildDir ?? "./build",
+      });
+      console.log(`[bract] prerender → ${written.length} files`);
+    }
     break;
   }
 
@@ -109,7 +123,10 @@ switch (command) {
     // output. Users can still override with `NODE_ENV=staging bractjs start`.
     if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
     const { createServer } = await import("../src/server/serve.ts");
-    createServer({ port: 3000, buildDir: "./build" });
+    const { loadUserConfig } = await import("../src/config/load.ts");
+    // The config carries runtime-relevant fields too (ssr, port, dirs).
+    const userCfg = await loadUserConfig();
+    createServer({ port: 3000, buildDir: "./build", ...userCfg });
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "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",

package/src/__tests__/build-path.test.ts

@@ -0,0 +1,29 @@
+import { test, expect, describe } from "bun:test";
+import { buildPath } from "../client/build-path.ts";
+
+describe("buildPath", () => {
+  test("substitutes a single :param", () => {
+    expect(buildPath("/blog/:id", { id: "42" })).toBe("/blog/42");
+  });
+
+  test("substitutes multiple params", () => {
+    expect(buildPath("/u/:user/post/:post", { user: "ann", post: "7" })).toBe("/u/ann/post/7");
+  });
+
+  test("passes static patterns through untouched", () => {
+    expect(buildPath("/about", {})).toBe("/about");
+    expect(buildPath("/", {})).toBe("/");
+  });
+
+  test("URL-encodes param values", () => {
+    expect(buildPath("/search/:q", { q: "a b/c" })).toBe("/search/a%20b%2Fc");
+  });
+
+  test("coerces numbers to strings", () => {
+    expect(buildPath("/n/:id", { id: 7 })).toBe("/n/7");
+  });
+
+  test("leaves an absent param's segment intact (surfaces as an obvious bad URL)", () => {
+    expect(buildPath("/blog/:id", {})).toBe("/blog/:id");
+  });
+});