@bractjs/bractjs 0.1.27 → 0.1.28

package/README.md

@@ -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,15 +411,16 @@ 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`
@@ -360,24 +431,48 @@ 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 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? }) => Promise<void>`
-Imperative soft navigation — the counterpart to `<Link>`. `to` autocompletes your routes (after codegen, §18) and `params` is typed per route; any string is still accepted.
+### `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("/about");                                  // static
-await navigate(`/blog/${id}`);                             // built string (also fine)
+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. Pass the route pattern as a generic to type the result against `RouteSearchParamsMap` (augment it per route, §18); an object shape also works.
+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<"/blog/:id">();
 const q = getParam("q");                        // string | null
@@ -385,12 +480,24 @@ 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 }`
@@ -426,16 +533,37 @@ export default function BlogLayout() {
 }
 ```
 
-### `<Link to params? prefetch? viewTransition?>`
-Soft-navigates without a full reload. After codegen (§18), `to` autocompletes your routes; for a dynamic route pass typed `params`. Building the URL yourself still works, so existing links need no changes.
+### `<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/:id" params={{ id: "42" }}>Read</Link>  {/* typed route + params */}
 <Link to={`/blog/${id}`}>Read</Link>                    {/* built string — also fine */}
-<Link to="/about" prefetch="hover">About</Link>         {/* preload chunk + loader on hover */}
+<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
@@ -573,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
@@ -614,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
@@ -759,7 +911,7 @@ bractjs codegen                       # ./app → ./app/route-types.gen.ts
 bractjs codegen ./app ./app/types.ts  # explicit paths
 ```
 
-Runs automatically during `bractjs build`. 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**:
+**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**:
 
 ```tsx
 <Link to="/blog/:id" params={{ id }} />     // ✅ "/blog/:id" autocompletes; params typed
@@ -936,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`)
@@ -1047,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 |
@@ -1062,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`).
@@ -1072,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`
 
@@ -1084,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`, `useParams`, `useNavigation`, `useFetcher`, `useSearchParams`, `useBlocker`, `useLocale`, `useLocalizedLink`
+**Hooks:** `useLoaderData`, `useActionData`, `useLocation`, `useParams`, `useNavigation`, `useNavigate`, `useFetcher`, `useFetchers`, `useRevalidator`, `useSearch`, `useSetSearch`, `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`
 
@@ -1100,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.
 
 ---
 

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.27",
+  "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__/codegen-write.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test";
+import { mkdir, rm, writeFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  writeRouteTypes,
+  explainStalenessForApp,
+} from "../codegen/route-codegen.ts";
+
+let appDir = "";
+
+beforeEach(async () => {
+  appDir = join(tmpdir(), `bract-codegen-write-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await mkdir(join(appDir, "routes"), { recursive: true });
+  await writeFile(join(appDir, "routes", "_index.tsx"), "export default () => null;");
+});
+
+afterEach(async () => {
+  await rm(appDir, { recursive: true, force: true });
+});
+
+describe("writeRouteTypes — idempotency", () => {
+  test("writes on first run, skips identical re-run, rewrites on route change", async () => {
+    const first = await writeRouteTypes(appDir);
+    expect(first.written).toBe(true);
+
+    const destStat = await stat(first.dest);
+    const mtime1 = destStat.mtimeMs;
+
+    // Identical re-run: no write (so no file-watcher event / editor reload loop).
+    const second = await writeRouteTypes(appDir);
+    expect(second.written).toBe(false);
+    expect((await stat(first.dest)).mtimeMs).toBe(mtime1);
+
+    // Add a route → content changes → write happens.
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    const third = await writeRouteTypes(appDir);
+    expect(third.written).toBe(true);
+  });
+});
+
+describe("explainStalenessForApp", () => {
+  test("missing generated file → reason mentions missing", async () => {
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/missing/);
+  });
+
+  test("fresh after codegen → null", async () => {
+    await writeRouteTypes(appDir);
+    expect(await explainStalenessForApp(appDir)).toBeNull();
+  });
+
+  test("added route → reports +1", async () => {
+    await writeRouteTypes(appDir);
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/\+1 added/);
+  });
+
+  test("removed route → reports -1", async () => {
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    await writeRouteTypes(appDir);
+    await rm(join(appDir, "routes", "about.tsx"));
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/-1 removed/);
+  });
+});

package/src/__tests__/codegen.test.ts

@@ -2,7 +2,11 @@ import { test, expect, describe, beforeAll, afterAll } from "bun:test";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { generateRouteTypes } from "../codegen/route-codegen.ts";
+import {
+  generateRouteTypes,
+  routesFingerprint,
+  readFingerprint,
+} from "../codegen/route-codegen.ts";
 
 let appDir = "";
 
@@ -29,6 +33,23 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/\| "\/users\/:id"/);
   });
 
+  test("emits a fingerprint matching routesFingerprint, and is deterministic", async () => {
+    const out = await generateRouteTypes(appDir);
+    // Header carries the route fingerprint.
+    const embedded = readFingerprint(out);
+    expect(embedded).toMatch(/^[0-9a-f]+$/);
+    expect(embedded).toBe(await routesFingerprint(["/", "/users/:id"]));
+    // Same input → byte-identical output (order-independent / reproducible).
+    expect(await generateRouteTypes(appDir)).toBe(out);
+    // Pattern union is sorted (deterministic across filesystems).
+    expect(out.indexOf('| "/"')).toBeLessThan(out.indexOf('| "/users/:id"'));
+  });
+
+  test("routesFingerprint is order-independent", async () => {
+    expect(await routesFingerprint(["/a", "/b"])).toBe(await routesFingerprint(["/b", "/a"]));
+    expect(await routesFingerprint(["/a"])).not.toBe(await routesFingerprint(["/a", "/b"]));
+  });
+
   test("wires the Register augmentation for typed routing", async () => {
     const regApp = join(tmpdir(), `bract-codegen-register-${Date.now()}`);
     await mkdir(join(regApp, "routes", "users"), { recursive: true });
@@ -45,7 +66,7 @@ describe("route-codegen — output shape", () => {
     // re-declared as bare top-level interfaces in the app file.
     expect(out).not.toMatch(/^export interface RouteSearchParamsMap/m);
     expect(out).not.toMatch(/^export interface RouteContextMap/m);
-    expect(out).toContain('import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs"');
+    expect(out).toContain('import type { RouteSearchParamsMap, RouteContextMap, InferSchemaOutput } from "@bractjs/bractjs"');
 
     // The Register seam carries the route union and a per-route params map.
     expect(out).toContain("interface Register {");
@@ -53,6 +74,12 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/"\/users\/:id": \{ id: string \};/); // dynamic route → typed params
     expect(out).toMatch(/"\/about": \{\};/);                   // static route → no params
 
+    // Schema-inferred search shapes: a per-route map derived from each route
+    // module's `searchSchema` export, registered under `searchOutput`.
+    expect(out).toContain("export type GeneratedSearchOutput = {");
+    expect(out).toContain('typeof import("./routes/about.tsx") extends { searchSchema: infer S }');
+    expect(out).toContain("searchOutput: GeneratedSearchOutput;");
+
     await rm(regApp, { recursive: true, force: true });
   });
 

package/src/__tests__/compile-safety.test.ts

@@ -51,6 +51,10 @@ const ALLOWED: Record<string, string[]> = {
   // calls it when no `registry` is provided; registry mode uses pickRouteModule
   // (a plain Record lookup, no import).
   "layout.ts": ["await import(filePath)"],
+  // renderSpaShell(): source-mode root.tsx load for the SPA shell. Compiled
+  // binaries always pass a moduleRegistry, which takes the registry branch
+  // (plain Record lookup) before this import is reached.
+  "spa.ts": ["await import(rootPath)"],
 };
 
 async function serverFiles(): Promise<string[]> {