@bractjs/bractjs 0.1.26 → 0.1.28

package/src/server/search.ts

@@ -0,0 +1,43 @@
+import { runSchema, type Schema } from "./validate.ts";
+
+// ── Raw extraction ─────────────────────────────────────────────────────────
+
+/**
+ * URLSearchParams → plain object. Repeated keys collapse into arrays
+ * (`?tag=a&tag=b` → `{ tag: ["a", "b"] }`), mirroring how `validate()`
+ * flattens FormData.
+ */
+export function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  for (const [key, value] of sp.entries()) {
+    const existing = out[key];
+    if (existing === undefined) out[key] = value;
+    else if (Array.isArray(existing)) existing.push(value);
+    else out[key] = [existing, value];
+  }
+  return out;
+}
+
+// ── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate a URL's search params against a route's optional `searchSchema`
+ * export (Zod/Valibot/standard-schema compatible — same duck typing as
+ * `validate()`).
+ *
+ * - No schema → the raw string record (back-compat: routes that never opted in
+ *   see exactly what `request.url` would give them).
+ * - Schema failure → throws the 400 `Response` from the validate machinery.
+ *   Loaders must never run on unvalidated input; leniency belongs in the
+ *   schema itself (`z.coerce.number().catch(1)` is the documented idiom for
+ *   URLs that must tolerate junk).
+ * - Success → the parsed, coerced object (numbers/booleans/arrays/defaults).
+ */
+export async function validateSearch(
+  schema: unknown,
+  url: URL,
+): Promise<Record<string, unknown>> {
+  const raw = searchParamsToObject(url.searchParams);
+  if (!schema) return raw;
+  return await runSchema(schema as Schema<Record<string, unknown>>, raw);
+}

package/src/server/serve.ts

@@ -1,6 +1,7 @@
 import { scanRoutes, type RouteFile } from "./scanner.ts";
-import { buildTrie } from "./matcher.ts";
+import { buildTrie, matchRoute } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
+import { renderSpaShell } from "./spa.ts";
 import { type ServerManifest } from "./render.ts";
 import { isDevRuntime, isExplicitDev } from "./env.ts";
 import { loadManifest } from "../build/manifest.ts";
@@ -24,10 +25,24 @@ export interface BractJSConfig {
   appDir: string;
   publicDir: string;
   manifest: ServerManifest;
+  /** WebSocket port for dev HMR (used by `bractjs dev` only). Default 3001. */
+  hmrPort?: number;
   /** Optional custom adapter (Cloudflare Workers, Deno, Node, etc.). Defaults to Bun.serve(). */
   adapter?: BractAdapter;
   /** i18n locale prefix routing (E2). */
   i18n?: I18nConfig;
+  /**
+   * SPA mode: `false` serves one static shell for every document GET instead
+   * of SSR. The server keeps running — /_data, actions, /_image, API routes
+   * and static assets behave exactly as in SSR mode ("no document SSR", not
+   * "no server"). Default `true`.
+   */
+  ssr?: boolean;
+  /**
+   * Paths to prerender at build time (SSG). Served from disk before dynamic
+   * SSR in production; requests with a query string stay dynamic.
+   */
+  prerender?: string[] | (() => string[] | Promise<string[]>);
   // Build options (used by src/build/bundler.ts)
   sourcemap?: "none" | "linked" | "inline" | "external";
   minify?: boolean;
@@ -129,6 +144,30 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     : loadServerActions(appDir);
   const moduleRegistry = config.moduleRegistry;
   const onError = config.onError;
+  const ssrEnabled = config.ssr !== false;
+
+  // SPA shell: production prefers the file `bractjs build` wrote; dev (or a
+  // missing file) renders it on demand so root.tsx edits show up. Cached per
+  // manifest in prod-without-file; never cached in dev.
+  let spaShellCache: { key: string; html: string } | null = null;
+  async function getSpaShell(manifest: ServerManifest): Promise<string> {
+    if (!isDevRuntime()) {
+      const file = Bun.file(join(buildDir, "client", "__spa.html"));
+      if (await file.exists()) return file.text();
+      const key = manifest.clientEntry;
+      if (spaShellCache?.key === key) return spaShellCache.html;
+      const html = await renderSpaShell(appDir, manifest, moduleRegistry);
+      spaShellCache = { key, html };
+      return html;
+    }
+    return renderSpaShell(appDir, manifest, moduleRegistry);
+  }
+
+  /** Prerendered file for a clean (query-free, dot-free) document path, or null. */
+  function prerenderFile(relHtmlOrJson: string): ReturnType<typeof Bun.file> | null {
+    if (relHtmlOrJson.split("/").some((s) => s === ".." || s === ".")) return null;
+    return Bun.file(join(buildDir, "client", "_prerender", relHtmlOrJson));
+  }
 
   return async function fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
@@ -196,6 +235,54 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     if (staticRes) return staticRes;
 
     const trie = await trieReady;
+    const isDocGet = request.method === "GET" || request.method === "HEAD";
+
+    // SPA mode: every document GET that matches a route gets the static
+    // shell. /_data (no trie match) and mutations fall through to the normal
+    // handler, so loaders/actions/CSRF behave exactly as in SSR mode.
+    if (!ssrEnabled && isDocGet && matchRoute(pathname, trie)) {
+      const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
+      return new Response(await getSpaShell(manifest), {
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-cache",
+        },
+      });
+    }
+
+    // Prerendered output (production): serve the build-time HTML / _data
+    // payload for clean URLs. A query string opts the request back into
+    // dynamic SSR — the static file was rendered without one.
+    if (!isDevRuntime() && isDocGet) {
+      if (pathname === "/_data") {
+        const target = url.searchParams.get("path") ?? "/";
+        const [targetPathname, targetSearch] = target.split("?");
+        if (!targetSearch) {
+          const rel = targetPathname === "/" ? "_data.json" : targetPathname.slice(1) + "/_data.json";
+          const f = prerenderFile(rel);
+          if (f && (await f.exists())) {
+            return new Response(f, {
+              headers: {
+                "Content-Type": "application/json",
+                "Cache-Control": "public, max-age=0, must-revalidate",
+              },
+            });
+          }
+        }
+      } else if (!url.search) {
+        const rel = pathname === "/" ? "index.html" : pathname.slice(1) + "/index.html";
+        const f = prerenderFile(rel);
+        if (f && (await f.exists())) {
+          return new Response(f, {
+            headers: {
+              "Content-Type": "text/html; charset=utf-8",
+              "Cache-Control": "public, max-age=0, must-revalidate",
+            },
+          });
+        }
+      }
+    }
+
     const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
     const handlerConfig: HandlerConfig = { appDir, publicDir, manifest, onError, moduleRegistry };
     return handleRequest(request, trie, handlerConfig);

package/src/server/spa.ts

@@ -0,0 +1,62 @@
+import { createElement, type ComponentType } from "react";
+import { join, resolve } from "node:path";
+import { renderRoute, type ServerManifest } from "./render.ts";
+import { BractJSProvider, type RouteManifest } from "../shared/context.ts";
+import type { ModuleRegistry } from "./layout.ts";
+
+/**
+ * Render the SPA-mode document shell: the app's root component around an
+ * empty outlet, with `ssrMode: "spa"` in the bootstrap payload. Served for
+ * every document GET when the config sets `ssr: false`; the client router
+ * resolves the actual route (module + /_data) after hydration.
+ *
+ * The root renders with NO loader data (its loader does not run for the
+ * shell) and a "/" location — roots that render loader- or location-dependent
+ * markup are not compatible with SPA mode. Loaders/actions stay fully
+ * functional at runtime: SPA mode means "no document SSR", not "no server".
+ */
+export async function renderSpaShell(
+  appDir: string,
+  manifest: ServerManifest,
+  registry?: ModuleRegistry,
+): Promise<string> {
+  let RootComponent: ComponentType = () => null;
+  if (registry) {
+    const rootMod = (registry["root.tsx"] ?? registry["root.ts"]) as { default?: ComponentType } | undefined;
+    if (rootMod?.default) RootComponent = rootMod.default;
+  } else {
+    const rootPath = resolve(join(appDir, "root.tsx"));
+    if (await Bun.file(rootPath).exists()) {
+      const mod = (await import(rootPath)) as { default?: ComponentType };
+      if (mod.default) RootComponent = mod.default;
+    }
+  }
+
+  const loaderData = { root: null, layouts: [], route: null };
+  const shell = createElement(BractJSProvider, {
+    value: {
+      loaderData: loaderData as unknown as Record<string, unknown>,
+      actionData: null,
+      params: {},
+      pathname: "/",
+      manifest: manifest as unknown as RouteManifest,
+      RouteComponent: undefined,
+      location: { pathname: "/", search: "", hash: "", state: null, key: "default" },
+      search: {},
+    },
+    children: createElement(RootComponent),
+  });
+
+  const res = await renderRoute({
+    shell,
+    loaderData: loaderData as unknown as Record<string, unknown>,
+    actionData: null,
+    params: {},
+    pathname: "/",
+    search: {},
+    manifest,
+    meta: [],
+    ssrMode: "spa",
+  });
+  return await res.text();
+}

package/src/server/stream-handler.ts

@@ -1,5 +1,6 @@
 import { resolveAction } from "./action-registry.ts";
 import { isExplicitDev } from "./env.ts";
+import { csrfHint } from "./csrf.ts";
 
 // ── SSE helpers ────────────────────────────────────────────────────────────
 
@@ -31,7 +32,7 @@ export async function handleStreamRequest(request: Request): Promise<Response |
   // it cross-origin without a CORS preflight, and the real client (useFetcher)
   // always sends it. This is strictly tighter than the /_action gate.
   if (!request.headers.get("X-BractJS-Action")) {
-    return new Response(sseChunk("error", { message: "Forbidden" }), {
+    return new Response(sseChunk("error", { message: isExplicitDev() ? csrfHint() : "Forbidden" }), {
       status: 403,
       headers: {
         "Content-Type": "text/event-stream",
@@ -70,6 +71,14 @@ export async function handleStreamRequest(request: Request): Promise<Response |
     async start(controller) {
       const encoder = new TextEncoder();
       try {
+        // SECURITY(medium): /_stream invokes the resolved action with NO
+        // caller-supplied arguments (GET carries no body, and we deliberately
+        // pass none). Any function reachable here therefore runs purely on
+        // server-side state. The X-BractJS-Action gate above blocks browser
+        // cross-origin abuse; the action-registry's RESERVED_ROUTE_EXPORTS
+        // filter keeps route lifecycle exports (loader/action/…) from ever
+        // being resolvable. Authors must still ensure stream actions are safe
+        // to call with no input and perform their own authorization.
         const result = await action();
         // If the action is an async generator, stream each value.
         if (result && typeof (result as AsyncIterable<unknown>)[Symbol.asyncIterator] === "function") {

package/src/server/validate.ts

@@ -14,7 +14,7 @@ interface SchemaWithSafeParse<T> {
   safeParse(input: unknown): SafeParseResult<T> | Promise<SafeParseResult<T>>;
 }
 
-type Schema<T> = SchemaWithParse<T> | SchemaWithSafeParse<T>;
+export type Schema<T> = SchemaWithParse<T> | SchemaWithSafeParse<T>;
 
 // ── Field error shape ─────────────────────────────────────────────────────
 
@@ -48,21 +48,15 @@ function toPlainObject(input: FormData | Record<string, unknown>): Record<string
 }
 
 /**
- * Validate `input` against a Zod-compatible or Valibot-compatible schema.
- *
- * - If the schema has `.safeParse()`: uses it to collect field errors and throws
- *   a typed `ValidationError` on failure (which the framework converts to a 400).
- * - If the schema only has `.parse()`: wraps it and re-throws the error as a
- *   `ValidationError` with a single `_` field containing the error message.
- *
- * Returns the parsed (coerced) data on success.
+ * Run a plain object through a Zod/Valibot-compatible schema. The shared core
+ * of `validate()` (action/form bodies) and `validateSearch()` (URL search
+ * params). Throws a 400 `Response` with `{ errors }` field errors on failure;
+ * returns the parsed (coerced) data on success.
  */
-export async function validate<T>(
+export async function runSchema<T>(
   schema: Schema<T>,
-  input: FormData | Record<string, unknown>,
+  plain: Record<string, unknown>,
 ): Promise<T> {
-  const plain = toPlainObject(input);
-
   if ("safeParse" in schema && typeof schema.safeParse === "function") {
     const result = await schema.safeParse(plain);
     if ((result as SafeParseResult<T>).success) {
@@ -87,3 +81,81 @@ export async function validate<T>(
     throw Response.json({ errors: fieldErrors }, { status: 400, statusText: "Validation failed" });
   }
 }
+
+/**
+ * Validate `input` against a Zod-compatible or Valibot-compatible schema.
+ *
+ * - If the schema has `.safeParse()`: uses it to collect field errors and throws
+ *   a typed `ValidationError` on failure (which the framework converts to a 400).
+ * - If the schema only has `.parse()`: wraps it and re-throws the error as a
+ *   `ValidationError` with a single `_` field containing the error message.
+ *
+ * Returns the parsed (coerced) data on success.
+ */
+export async function validate<T>(
+  schema: Schema<T>,
+  input: FormData | Record<string, unknown>,
+): Promise<T> {
+  return runSchema(schema, toPlainObject(input));
+}
+
+// ── Non-throwing validation (ergonomic action idiom) ───────────────────────
+
+export type SafeValidateResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; fieldErrors: FieldErrors; firstError: string };
+
+/**
+ * Like {@link validate}, but returns a result instead of throwing — the
+ * ergonomic shape for actions that want to render field errors:
+ *
+ * ```ts
+ * const r = await safeValidate(PostSchema, formData);
+ * if (!r.ok) return { error: r.firstError, fieldErrors: r.fieldErrors };
+ * usePost(r.data);
+ * ```
+ *
+ * `firstError` is the first message across all fields, or a generic fallback.
+ */
+export async function safeValidate<T>(
+  schema: Schema<T>,
+  input: FormData | Record<string, unknown>,
+): Promise<SafeValidateResult<T>> {
+  try {
+    const data = await runSchema(schema, toPlainObject(input));
+    return { ok: true, data };
+  } catch (err) {
+    if (isValidationResponse(err)) {
+      const { fieldErrors, firstError } = await readValidationError(err);
+      return { ok: false, fieldErrors, firstError };
+    }
+    throw err; // not a validation failure — let it propagate
+  }
+}
+
+/**
+ * True for the 400 `Response` thrown by {@link validate} / `searchSchema`
+ * validation (identified by status 400 + `statusText "Validation failed"`).
+ * Use it in the try/catch idiom when you keep calling `validate()` directly.
+ */
+export function isValidationResponse(value: unknown): value is Response {
+  return value instanceof Response && value.status === 400 && value.statusText === "Validation failed";
+}
+
+/**
+ * Parse the `{ errors }` body of a validation 400 `Response` into field errors
+ * plus the first message. Tolerant of a non-JSON / unexpected body.
+ */
+export async function readValidationError(
+  res: Response,
+): Promise<{ fieldErrors: FieldErrors; firstError: string }> {
+  const fallback = "Please check your input.";
+  try {
+    const body = (await res.clone().json()) as { errors?: FieldErrors };
+    const fieldErrors = body.errors ?? {};
+    const firstError = Object.values(fieldErrors)[0]?.[0] ?? fallback;
+    return { fieldErrors, firstError };
+  } catch {
+    return { fieldErrors: {}, firstError: fallback };
+  }
+}

package/src/shared/context.ts

@@ -1,4 +1,5 @@
 import { createContext, useContext, createElement, type ComponentType, type ReactNode } from "react";
+import type { RouterLocation } from "./route-types.ts";
 
 export interface RouteManifest {
   [routeId: string]: {
@@ -15,6 +16,10 @@ export interface BractJSContextValue {
   manifest: RouteManifest;
   /** SSR-only: the matched route's default export so <Outlet> can render it without ClientRouter */
   RouteComponent?: ComponentType;
+  /** The request's location, so `useLocation()` works during SSR (hash is always ""). */
+  location?: RouterLocation;
+  /** Validated search params (route `searchSchema` output), so `useSearch()` works during SSR. */
+  search?: Record<string, unknown>;
 }
 
 export const BractJSContext = createContext<BractJSContextValue>(null!);

package/src/shared/define-actions.ts

@@ -0,0 +1,39 @@
+import type { ActionArgs } from "./route-types.ts";
+import { isExplicitDev } from "../server/env.ts";
+
+type IntentHandler = (args: ActionArgs) => unknown;
+
+/**
+ * Compose a single route `action` from per-intent handlers, dispatching on the
+ * form's `intent` field. Pairs with `<Form intent="...">` / `<fetcher.Form
+ * intent="...">`, which render the matching hidden input:
+ *
+ * ```ts
+ * export const action = defineActions({
+ *   add:    ({ formData }) => addTodo(formText(formData, "title")),
+ *   delete: ({ formData }) => deleteTodo(formText(formData, "id")),
+ * });
+ * ```
+ *
+ * A missing or unknown intent returns a 400 `Response` (dev lists the known
+ * intents; prod is terse). Each handler receives the full {@link ActionArgs}.
+ */
+export function defineActions<M extends Record<string, IntentHandler>>(
+  handlers: M,
+): (args: ActionArgs) => Promise<Awaited<ReturnType<M[keyof M]>> | Response> {
+  type Out = Awaited<ReturnType<M[keyof M]>> | Response;
+  const dispatch = async (args: ActionArgs): Promise<Out> => {
+    const raw = args.formData.get("intent");
+    const intent = typeof raw === "string" ? raw : "";
+    const handler = handlers[intent];
+    if (!handler) {
+      const known = Object.keys(handlers);
+      const message = isExplicitDev()
+        ? `Unknown action intent ${JSON.stringify(intent)}. Known intents: ${known.join(", ") || "(none)"}.`
+        : "Unknown action intent.";
+      return Response.json({ error: message }, { status: 400 });
+    }
+    return (await handler(args)) as Out;
+  };
+  return dispatch;
+}

package/src/shared/form-data.ts

@@ -0,0 +1,34 @@
+// Small ergonomics for reading FormData in actions, where `.get()` returns
+// `string | File | null` and almost every call site coerces to a string.
+
+/**
+ * Read a string field from FormData. Returns `""` when the field is missing or
+ * is a File (upload) — never `null`/`File`, so it drops straight into code that
+ * expects a string. Replaces the `String(formData.get("x") ?? "")` dance.
+ */
+export function formText(formData: FormData, key: string): string {
+  const value = formData.get(key);
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Collect string fields from FormData into a plain object. With no `keys`, every
+ * string entry is included (Files are skipped, first occurrence wins per key);
+ * with `keys`, only those fields (each defaulting to `""`). Handy for passing a
+ * typed subset of a form to a model function.
+ */
+export function formValues(
+  formData: FormData,
+  keys?: string[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (keys) {
+    for (const key of keys) out[key] = formText(formData, key);
+    return out;
+  }
+  for (const [key, value] of formData.entries()) {
+    if (key in out) continue; // first occurrence wins (mirrors FormData.get)
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}

package/src/shared/route-types.ts

@@ -1,15 +1,57 @@
 import type { Deferred } from "./deferred.ts";
 
-export interface LoaderArgs {
+/**
+ * A parsed navigation location. `key` is the stable identity of the history
+ * entry (used by scroll restoration); `state` is the value passed via
+ * `navigate(to, { state })`. During SSR `hash` is always `""` (the fragment
+ * never reaches the server) and `key` is `"default"`.
+ */
+export interface RouterLocation {
+  pathname: string;
+  /** Raw query string including the leading `?`, or `""`. */
+  search: string;
+  /** Fragment including the leading `#`, or `""`. */
+  hash: string;
+  state: unknown;
+  key: string;
+}
+
+export interface LoaderArgs<TSearch extends Record<string, unknown> = Record<string, unknown>> {
   request: Request;
   params: Record<string, string>;
   context: Record<string, unknown>;
+  /**
+   * The request's search params, validated/coerced by the route's
+   * `searchSchema` export when present; otherwise the raw string record
+   * (repeated keys become arrays).
+   *
+   * Parameterize to skip the cast in routes with a schema:
+   * `loader({ search }: LoaderArgs<BoardSearch>)`.
+   */
+  search: TSearch;
 }
 
-export interface ActionArgs extends LoaderArgs {
+export interface ActionArgs<TSearch extends Record<string, unknown> = Record<string, unknown>>
+  extends LoaderArgs<TSearch> {
   formData: FormData;
 }
 
+/**
+ * The data a route's loader resolves to, for typing `useLoaderData`.
+ *
+ * Pass the loader FUNCTION type and it unwraps the return (awaited, with the
+ * `Response` redirect/throw branch removed): `useLoaderData<typeof loader>()`.
+ * Pass a plain object type and it's returned as-is (back-compat):
+ * `useLoaderData<HomeData>()`. `Deferred<V>` fields are preserved — that is the
+ * shape the component receives during streaming SSR (unwrap them with `<Await>`).
+ */
+export type LoaderData<T> = T extends (...args: never[]) => unknown
+  ? Exclude<Awaited<ReturnType<T>>, Response>
+  : T;
+
+/** The data a route's action resolves to, for typing `useActionData`. See {@link LoaderData}. */
+export type ActionData<T> = LoaderData<T>;
+
 export type MetaDescriptor =
   | { title: string }
   | { name: string; content: string }
@@ -37,17 +79,56 @@ export interface BeforeLoadArgs {
   params: Record<string, string>;
   context: Record<string, unknown>;
   location: { pathname: string; search: string };
+  /** Validated search params (server-side only; absent in the client-side guard). */
+  search?: Record<string, unknown>;
 }
 
 export type BeforeLoadFunction = (
   args: BeforeLoadArgs,
 ) => void | Response | Promise<void | Response>;
 
+/**
+ * Decide whether loader data should be refetched. Evaluated on the CLIENT for
+ * (a) the stale-while-revalidate background refetch and (b) the automatic
+ * revalidation after a `<Form>`/fetcher mutation. Return
+ * `args.defaultShouldRevalidate` (true) to keep the default behavior.
+ */
+export interface ShouldRevalidateArgs {
+  currentUrl: URL;
+  nextUrl: URL;
+  /** Present when the revalidation was triggered by a mutation. */
+  formMethod?: string;
+  /** HTTP status the action responded with, when mutation-triggered. */
+  actionStatus?: number;
+  defaultShouldRevalidate: boolean;
+}
+
+export type ShouldRevalidateFunction = (args: ShouldRevalidateArgs) => boolean;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
   beforeLoad?: BeforeLoadFunction;
+  shouldRevalidate?: ShouldRevalidateFunction;
+  /**
+   * Zod/Valibot-compatible schema validating the route's search params before
+   * loaders run. Failure → 400; use `.catch()`/`.default()` per field for
+   * URLs that must tolerate junk values.
+   */
+  searchSchema?: unknown;
+  /**
+   * Selective SSR (TanStack-style):
+   * - `true` (default) — full document SSR with loader data.
+   * - `"data-only"` — loaders run on the server, but the component renders
+   *   only on the client (`Fallback` SSRs in its place).
+   * - `false` — neither the route loader nor the component runs during
+   *   document SSR; the client fetches `/_data` after hydration. `beforeLoad`
+   *   STILL runs on the server — it is the auth gate.
+   */
+  ssr?: boolean | "data-only";
+  /** SSR'd in the component's place for `ssr: false` / `"data-only"` routes (HydrateFallback equivalent). */
+  Fallback?: React.ComponentType;
   handle?: Record<string, unknown>;
   ErrorBoundary?: React.ComponentType<{ error: unknown }>;
   default?: React.ComponentType;

package/templates/new-app/app/root.tsx

@@ -1,6 +1,6 @@
 // This is the root layout for your BractJS app.
 // Every route renders inside this component.
-import { Scripts, LiveReload, Outlet } from "@bractjs/bractjs";
+import { Scripts, LiveReload, Outlet, ScrollRestoration } from "@bractjs/bractjs";
 
 export default function Root() {
   return (
@@ -12,6 +12,7 @@ export default function Root() {
       </head>
       <body>
         <Outlet />
+        <ScrollRestoration />
         <Scripts />
         <LiveReload />
       </body>

package/templates/new-app/bractjs.config.ts

@@ -1,14 +1,9 @@
-import type { BractJSConfig } from "@bractjs/bractjs";
+import { defineConfig } from "@bractjs/bractjs";
 
-const config: BractJSConfig = {
+// All fields are optional and merged over BractJS defaults. `defineConfig`
+// gives you autocomplete + type-checking without annotating the full type.
+// (The build manifest is injected at runtime — you never set it here.)
+export default defineConfig({
   port: 3000,
-  appDir: "./app",
-  publicDir: "./public",
-  buildDir: "./build",
-  manifest: { clientEntry: "", routes: {} }, // populated by `bractjs build`
-  minify: true,
-  sourcemap: "external",
-  clientEnv: [],
-};
-
-export default config;
+  clientEnv: [], // process.env keys to expose to the client bundle
+});

package/types/config.d.ts

@@ -1,5 +1,6 @@
 import type { BunPlugin } from "bun";
 import type { RouteFile, RouteModule } from "./route.d.ts";
+import type { BractAdapter, I18nConfig, OnErrorHook } from "./index.d.ts";
 
 export interface BractJSConfig {
   /** TCP port to listen on. Default: 3000. */
@@ -20,10 +21,20 @@ export interface BractJSConfig {
   clientEnv?: string[];
   /** User Bun bundler plugins appended to the client build (e.g. bun-plugin-tailwind). */
   plugins?: BunPlugin[];
+  /** Directory for the transformed-image cache. Default: ".bract-image-cache". */
+  imageCacheDir?: string;
+  /** WebSocket port for dev HMR (used by `bractjs dev` only). Default 3001. */
+  hmrPort?: number;
+  /** Custom server adapter (Cloudflare Workers, Deno, Node, etc.). Defaults to Bun.serve(). */
+  adapter?: BractAdapter;
+  /** i18n locale-prefix routing config consumed by the i18n utilities. */
+  i18n?: I18nConfig;
   /** Called once after the server starts listening. Use to open DB connections, warm caches, etc. */
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error (loader/action throws, uncaught exceptions). Redirects and HttpErrors are not reported. */
+  onError?: OnErrorHook;
   /**
    * Pre-scanned route list. Typically imported from `app/_generated/routes.ts`.
    * Required for `bun build --compile` binaries where the routes/ directory
@@ -41,6 +52,14 @@ export interface BractJSConfig {
    * proxy plugin hashed during the client build.
    */
   actionModules?: Array<{ relPath: string; mod: Record<string, unknown> }>;
+  /**
+   * SPA mode: `false` serves one static shell for every document GET instead
+   * of SSR ("no document SSR", not "no server" — /_data, actions, images and
+   * API routes keep working). Default `true`.
+   */
+  ssr?: boolean;
+  /** Paths to prerender at build time (SSG); served from disk before dynamic SSR. */
+  prerender?: string[] | (() => string[] | Promise<string[]>);
 }
 
 export interface ServerManifest {
@@ -60,4 +79,6 @@ export interface BuildConfig {
   minify?: boolean;
   clientEnv?: string[];
   plugins?: import("bun").BunPlugin[];
+  /** SPA mode: when `false`, the build also emits the static document shell. */
+  ssr?: boolean;
 }