@bractjs/bractjs 0.1.27 → 0.1.29

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 }
@@ -33,21 +75,149 @@ export type MetaFunction<T = unknown> = (
   args: MetaArgs<T>
 ) => MetaDescriptor[];
 
+export interface HeadersArgs<T = unknown> {
+  /** This route's loader data (the route slice, already awaited). */
+  loaderData: T;
+  params: Record<string, string>;
+  request: Request;
+  /**
+   * The merged headers contributed by ancestors in the chain (root → layout →
+   * this route). Spread these to inherit, or override individual keys. Each
+   * `headers()` in the chain runs in order and sees what came before it.
+   */
+  parentHeaders: Headers;
+}
+
+/**
+ * A route/layout/root module's optional `headers` export, used to set
+ * response headers (e.g. `Cache-Control`, `ETag`, `Vary`) on the document and
+ * `/_data` responses. Runs in chain order (root → layout → route); the
+ * innermost value wins per key. Returns a `HeadersInit` (object, array of
+ * tuples, or `Headers`).
+ */
+export type HeadersFunction<T = unknown> = (
+  args: HeadersArgs<T>
+) => HeadersInit;
+
+/**
+ * A nested route-middleware function. Runs on the server in chain order
+ * (root → layout → route) before `beforeLoad`, the action, and loaders. Call
+ * `next()` to continue, or return a `Response` to short-circuit. The `context`
+ * object is shared and mutable across the whole chain (and into loaders).
+ */
+export type RouteMiddlewareFunction = (
+  ctx: { request: Request; params: Record<string, string>; context: Record<string, unknown> },
+  next: () => Promise<Response>,
+) => Promise<Response>;
+
 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;
+
+/**
+ * A route's optional client loader (RR7-style). Runs in the browser on
+ * navigation to the route instead of just fetching the server loader. Call
+ * `serverLoader()` to get this route's server loader data (the `/_data`
+ * payload's route slice). Set `clientLoader.hydrate = true` to also run it
+ * during the initial hydration of an SSR'd document.
+ *
+ * Whatever it resolves to becomes the route's `useLoaderData()` value.
+ */
+export interface ClientLoaderFunction<T = unknown> {
+  (args: {
+    request: Request;
+    params: Record<string, string>;
+    search: Record<string, unknown>;
+    /** Fetch this route's server loader data (the `/_data` route slice). */
+    serverLoader: () => Promise<unknown>;
+  }): Promise<T> | T;
+  /** Run on initial hydration too (default: only on client navigation). */
+  hydrate?: boolean;
+}
+
+/**
+ * A route's optional client action (RR7-style). Runs in the browser on a
+ * `<Form>`/fetcher submission to the route instead of POSTing directly. Call
+ * `serverAction()` to invoke the server action and get its data. Whatever it
+ * resolves to becomes the route's `useActionData()` value.
+ */
+export type ClientActionFunction<T = unknown> = (args: {
+  request: Request;
+  params: Record<string, string>;
+  formData: FormData;
+  /** Invoke this route's server action and get its returned data. */
+  serverAction: () => Promise<unknown>;
+}) => Promise<T> | T;
+
 export interface RouteModule<TLoader = unknown, TAction = unknown> {
   loader?: LoaderFunction<TLoader>;
   action?: ActionFunction<TAction>;
+  /** Browser-side loader; see {@link ClientLoaderFunction}. */
+  clientLoader?: ClientLoaderFunction<TLoader>;
+  /** Browser-side action; see {@link ClientActionFunction}. */
+  clientAction?: ClientActionFunction<TAction>;
   meta?: MetaFunction<TLoader>;
+  /**
+   * Set response headers (`Cache-Control`, `ETag`, `Vary`, CDN hints, …) for
+   * this route's document and `/_data` responses. Runs in chain order
+   * (root → layout → route); innermost wins per key, and each call receives the
+   * `parentHeaders` accumulated so far. Skipped for mutations and error responses.
+   */
+  headers?: HeadersFunction<TLoader>;
+  /**
+   * Nested middleware for this route/layout/root. Runs on the server in chain
+   * order (root → layout → route) before `beforeLoad`/action/loaders, with a
+   * shared mutable `context`. A single function or an array. Return a
+   * `Response` to short-circuit; call `next()` to continue. Runs *inside* the
+   * global `pipeline` middleware.
+   */
+  middleware?: RouteMiddlewareFunction | RouteMiddlewareFunction[];
   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;
@@ -60,3 +230,22 @@ export interface RouteDefinition {
   parentId?: string;
   index?: boolean;
 }
+
+/**
+ * One entry in the matched route chain, as returned by `useMatches()`. The
+ * array runs outermost → innermost: root, then each layout, then the leaf
+ * route. Use it for breadcrumbs and conditional chrome driven by each route's
+ * `handle` export.
+ */
+export interface RouteMatch<TData = unknown, THandle = Record<string, unknown>> {
+  /** Stable id of the matched module — its appDir-relative file path (e.g. "routes/blog/[id].tsx", "root.tsx"). */
+  id: string;
+  /** The active URL pathname (same for every entry — they all share the matched location). */
+  pathname: string;
+  /** The matched route params (shared across the chain). */
+  params: Record<string, string>;
+  /** This module's loader data slice (root / the matching layout / the route). */
+  data: TData;
+  /** This module's static `handle` export, or `undefined` if none. */
+  handle: THandle | undefined;
+}

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,23 @@ 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;
+  /** Hard ceiling (bytes) on any incoming request body, enforced by the Bun
+   *  adapter regardless of advertised Content-Length. Default 16 MiB. */
+  maxRequestBodySize?: number;
+  /** 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 +55,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 +82,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;
 }

package/types/index.d.ts

@@ -4,8 +4,11 @@ import type { ReactNode, Context, CSSProperties } from "react";
 export type {
   LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
   LoaderFunction, ActionFunction, MetaFunction, RouteModule,
-  RouteFile, Segment,
+  RouteFile, Segment, RouterLocation,
+  ShouldRevalidateArgs, ShouldRevalidateFunction,
+  LoaderData, ActionData,
 } from "./route.d.ts";
+import type { RouterLocation, LoaderData, ActionData, ActionArgs } from "./route.d.ts";
 
 // ── Config + Server ───────────────────────────────────────────────────────
 export type { BractJSConfig, ServerManifest, BuildConfig } from "./config.d.ts";
@@ -18,9 +21,15 @@ export interface RenderOptions {
   actionData: unknown;
   params: Record<string, string>;
   pathname: string;
+  /** Validated search params — hydrates `useSearch()` on the client. */
+  search?: Record<string, unknown>;
   manifest: ServerManifest;
   meta: MetaDescriptor[];
   status?: number;
+  routeFile?: string;
+  nonce?: string;
+  /** Set when the document did not SSR the route component (selective SSR / SPA shell). */
+  ssrMode?: "client-only" | "data-only" | "spa";
 }
 
 export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
@@ -64,6 +73,10 @@ export interface BractJSContextValue {
   params: Record<string, string>;
   pathname: string;
   manifest: RouteManifest;
+  /** The request's location, so `useLocation()` works during SSR (hash is always ""). */
+  location?: RouterLocation;
+  /** Validated search params, so `useSearch()` works during SSR. */
+  search?: Record<string, unknown>;
 }
 export declare const BractJSContext: Context<BractJSContextValue>;
 export declare function BractJSProvider(props: { value: BractJSContextValue; children: ReactNode }): ReactNode;
@@ -80,6 +93,7 @@ import type { MiddlewareFn, MiddlewareContext } from "./middleware.d.ts";
 
 export declare class MiddlewarePipeline {
   use(fn: MiddlewareFn): this;
+  clear(): this;
   run(ctx: MiddlewareContext, handler: () => Promise<Response>): Promise<Response>;
 }
 export declare const pipeline: MiddlewarePipeline;
@@ -93,16 +107,24 @@ export declare function authGuard(options: AuthGuardOptions): MiddlewareFn;
 
 // ── API routes (C1) ───────────────────────────────────────────────────────
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ApiRouteOptions {
+  /** CSRF protection for this route. Default `true` for mutating methods
+   *  (POST/PUT/PATCH/DELETE). Set `false` only for endpoints that don't trust
+   *  ambient credentials (webhooks, token-authenticated/public APIs). */
+  csrf?: boolean;
+}
 export interface ApiRouteDefinition<TMethod extends HttpMethod, TPath extends string, TInput, TOutput> {
   method: TMethod;
   path: TPath;
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>;
+  csrf: boolean;
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export declare function route<TMethod extends HttpMethod, TPath extends string, TInput, TOutput>(
   method: TMethod,
   path: TPath,
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>,
+  options?: ApiRouteOptions,
 ): ApiRouteDefinition<TMethod, TPath, TInput, TOutput>;
 export type AppApiRoutes = never; // users extend this via codegen
 
@@ -129,6 +151,46 @@ export declare function validate<T>(
   input: FormData | Record<string, unknown>,
 ): Promise<T>;
 
+export type SafeValidateResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; fieldErrors: FieldErrors; firstError: string };
+/** Non-throwing validate(): returns a result instead of throwing a 400. */
+export declare function safeValidate<T>(
+  schema: { safeParse?(i: unknown): unknown } | { parse(i: unknown): T },
+  input: FormData | Record<string, unknown>,
+): Promise<SafeValidateResult<T>>;
+/** True for the 400 Response thrown by validate()/searchSchema validation. */
+export declare function isValidationResponse(value: unknown): value is Response;
+/** Parse the `{ errors }` body of a validation 400 into field errors + first message. */
+export declare function readValidationError(
+  res: Response,
+): Promise<{ fieldErrors: FieldErrors; firstError: string }>;
+
+// ── FormData helpers ──────────────────────────────────────────────────────
+/** String field from FormData; "" when missing or a File. */
+export declare function formText(formData: FormData, key: string): string;
+/** Collect string fields from FormData (all, or a named subset). */
+export declare function formValues(formData: FormData, keys?: string[]): Record<string, string>;
+
+// ── Prototype-pollution guards ────────────────────────────────────────────
+/** Deep-scan a parsed JSON value for `__proto__`/`constructor`/`prototype`
+ *  keys. Fails closed past an internal depth cap. Returns true if found. */
+export declare function hasForbiddenKey(value: unknown, depth?: number): boolean;
+/** Build a null-prototype object from entries, so a key named `__proto__`
+ *  lands as a plain own property instead of mutating the prototype. */
+export declare function nullProtoFromEntries<V>(entries: Iterable<readonly [string, V]>): Record<string, V>;
+
+// ── Search-param validation ───────────────────────────────────────────────
+/** URLSearchParams → plain object; repeated keys collapse into arrays. */
+export declare function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]>;
+/**
+ * Validate a URL's search params against a route's `searchSchema`. No schema →
+ * the raw string record; failure → throws a 400 Response with field errors.
+ */
+export declare function validateSearch(schema: unknown, url: URL): Promise<Record<string, unknown>>;
+/** Serialize a search object back into a query string (leading `?`, or ""). */
+export declare function serializeSearch(search: Record<string, unknown>): string;
+
 // ── Typed-routing registration seam ───────────────────────────────────────
 // Mirror of src/client/registry.ts. Augment `Register` (done by `bractjs codegen`
 // in app/route-types.gen.ts) to make <Link>/useNavigate/useParams/useSearchParams
@@ -151,10 +213,21 @@ export type RegisteredParamsMap =
   Register extends { routes: { params: infer P } } ? P : Record<string, Record<string, string>>;
 export type RegisteredSearchMap =
   Register extends { routes: { search: infer S } } ? S : Record<string, Record<string, string>>;
+export type RegisteredSearchOutputMap =
+  Register extends { routes: { searchOutput: infer S } } ? S : Record<string, Record<string, unknown>>;
 export type ParamsFor<TTo> =
   TTo extends keyof RegisteredParamsMap ? RegisteredParamsMap[TTo] : Record<string, string>;
 export type SearchFor<TTo> =
   TTo extends keyof RegisteredSearchMap ? RegisteredSearchMap[TTo] : Record<string, string>;
+/** Validated (schema-output) search object for a specific route literal. */
+export type SearchOutputFor<TTo> =
+  TTo extends keyof RegisteredSearchOutputMap ? RegisteredSearchOutputMap[TTo] : Record<string, unknown>;
+/** Infer the output type of a Zod/Valibot-compatible schema (duck-typed z.infer). */
+export type InferSchemaOutput<S> =
+  S extends { parse(input: unknown): infer T } ? T :
+  S extends { safeParse(input: unknown): infer R }
+    ? (Awaited<R> extends { data?: infer T } ? NonNullable<T> : Record<string, unknown>)
+    : Record<string, unknown>;
 export declare function buildPath(pattern: string, params: Record<string, string | number>): string;
 
 // ── Client components ─────────────────────────────────────────────────────
@@ -165,18 +238,37 @@ export declare function Outlet(): ReactNode;
 export type LinkProps<TTo extends RegisteredRoutes = RegisteredRoutes> = {
   to: TTo | (string & {});
   params?: ParamsFor<TTo>;
-  prefetch?: "hover" | "none";
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** When to prefetch the target's chunk + loader data. Default "none". */
+  prefetch?: "none" | "intent" | "hover" | "viewport" | "render";
   viewTransition?: boolean;
+  /** Replace the current history entry instead of pushing. */
+  replace?: boolean;
   children?: ReactNode;
   className?: string;
   [key: string]: unknown;
 };
 export declare function Link<TTo extends RegisteredRoutes = RegisteredRoutes>(props: LinkProps<TTo>): ReactNode;
 
-export interface FormProps { method?: "post" | "put" | "delete"; action?: string; children?: ReactNode; [key: string]: unknown; }
+export interface ScrollRestorationProps {
+  /** Derive the storage key for a location. Default: `location.key`. */
+  getKey?: (location: RouterLocation) => string;
+  storageKey?: string;
+}
+/** Restores scroll on back/forward, scrolls to top (or `#hash`) on new navigations. Render once in root.tsx. */
+export declare function ScrollRestoration(props?: ScrollRestorationProps): null;
+
+export interface FormProps { method?: "post" | "put" | "delete"; action?: string; /** Renders a hidden `intent` input (pairs with defineActions()). */ intent?: string; children?: ReactNode; [key: string]: unknown; }
 export declare function Form(props: FormProps): ReactNode;
 
-export interface AwaitProps<T> { resolve: Promise<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
+// ── defineActions (intent dispatch) ───────────────────────────────────────
+/** Compose a route action from per-intent handlers, dispatching on the form's `intent` field. */
+export declare function defineActions<M extends Record<string, (args: ActionArgs) => unknown>>(
+  handlers: M,
+): (args: ActionArgs) => Promise<Awaited<ReturnType<M[keyof M]>> | Response>;
+
+export interface AwaitProps<T> { resolve: Promise<T> | Deferred<T>; fallback: ReactNode; children: (data: T) => ReactNode; }
 export declare function Await<T>(props: AwaitProps<T>): ReactNode;
 
 export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
@@ -197,30 +289,90 @@ export interface ImageProps {
 export declare function Image(props: ImageProps): ReactNode;
 
 // ── Client hooks ──────────────────────────────────────────────────────────
-export declare function useLoaderData<T = unknown>(): T;
-export declare function useActionData<T = unknown>(): T | null;
+// Pass the loader/action function type to infer the data — useLoaderData<typeof loader>().
+export declare function useLoaderData<T = unknown>(): LoaderData<T>;
+export declare function useActionData<T = unknown>(): ActionData<T> | null;
+/** The current location — reactive on the client, request-derived during SSR. */
+export declare function useLocation(): RouterLocation;
 export declare function useParams<TTo extends string>(): ParamsFor<TTo>;
 export declare function useParams<T extends Record<string, string> = Record<string, string>>(): T;
 export type NavigationState = "idle" | "loading" | "submitting";
 export declare function useNavigation(): { state: NavigationState };
 
-export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> { params?: ParamsFor<TTo>; }
+export interface NavigateOptions<TTo extends RegisteredRoutes = RegisteredRoutes> {
+  params?: ParamsFor<TTo>;
+  /** Search params for the target, typed by its `searchSchema` (replaces any query in `to`). */
+  search?: Partial<SearchOutputFor<TTo>>;
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+  /** Arbitrary history state, readable via `useLocation().state` after navigating. */
+  state?: unknown;
+}
 export interface NavigateFn {
   <TTo extends RegisteredRoutes>(to: TTo | (string & {}), options?: NavigateOptions<TTo>): Promise<void>;
 }
 export declare function useNavigate(): NavigateFn;
+
+// ── Fetchers ──────────────────────────────────────────────────────────────
+export type FetcherState = "idle" | "loading" | "submitting";
+export interface FetcherEntry {
+  key: string;
+  state: FetcherState;
+  data: unknown;
+  /** The submitted form data while a submission is in flight — the optimistic-UI source. */
+  formData?: FormData;
+  formMethod?: string;
+}
+export interface FetcherFormProps {
+  method?: "post" | "put" | "delete";
+  action?: string;
+  /** Renders a hidden `intent` input (pairs with defineActions()). */
+  intent?: string;
+  children?: ReactNode;
+  [key: string]: unknown;
+}
 export interface FetcherResult {
   data: unknown;
-  state: NavigationState;
+  state: FetcherState;
+  formData?: FormData;
+  formMethod?: string;
+  key: string;
   load(path: string): Promise<void>;
   submit(path: string, opts: { method: string; body: FormData | Record<string, string> }): Promise<void>;
+  /** A form that submits through this fetcher (no navigation, no history). */
+  Form: (props: FetcherFormProps) => ReactNode;
 }
 export interface StreamFetcherResult<T = unknown> {
+  /** @deprecated Never emitted — call `connect(actionId)` instead. Removed in 0.2. */
   events: AsyncGenerator<T>;
   connect(actionId: string): AsyncGenerator<T>;
 }
-export declare function useFetcher(): FetcherResult;
+export interface UseFetcherOptions { key?: string; stream?: boolean }
+export declare function useFetcher(opts?: { key?: string }): FetcherResult;
 export declare function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
+/** Every active fetcher — the cross-component view for optimistic UI. */
+export declare function useFetchers(): FetcherEntry[];
+
+// ── Revalidation ──────────────────────────────────────────────────────────
+export interface Revalidator {
+  revalidate(): Promise<void>;
+  state: "idle" | "loading";
+}
+/** Manually re-run the active route's loaders (respects `shouldRevalidate`). */
+export declare function useRevalidator(): Revalidator;
+
+// ── Typed search ──────────────────────────────────────────────────────────
+/** The current route's VALIDATED search params (its `searchSchema` output). */
+export declare function useSearch<TTo extends string>(): SearchOutputFor<TTo>;
+export declare function useSearch<T extends Record<string, unknown>>(): T;
+export interface SetSearchOptions { replace?: boolean }
+export type SetSearchFn<T extends Record<string, unknown>> = (
+  updater: Partial<T> | ((prev: T) => Partial<T>),
+  options?: SetSearchOptions,
+) => Promise<void>;
+/** Merge a patch into the current search params and soft-navigate (loaders re-run). */
+export declare function useSetSearch<TTo extends string>(): SetSearchFn<SearchOutputFor<TTo>>;
+export declare function useSetSearch<T extends Record<string, unknown>>(): SetSearchFn<T>;
 
 export interface SearchParamsResult<T extends Record<string, string> = Record<string, string>> {
   searchParams: URLSearchParams;
@@ -316,3 +468,24 @@ export interface DevServer {
 export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
 
 export declare function loadUserConfig(): Promise<Partial<BractJSConfig>>;
+
+/** Identity helper for bractjs.config.ts — wrap your default export for autocomplete + type-checking. */
+export declare function defineConfig(config: Partial<BractJSConfig>): Partial<BractJSConfig>;
+
+// ── Prerendering / SPA shell ──────────────────────────────────────────────
+export interface PrerenderOptions {
+  prerender: string[] | (() => string[] | Promise<string[]>);
+  appDir?: string;
+  publicDir?: string;
+  buildDir?: string;
+  manifest?: ServerManifest;
+}
+export interface PrerenderResult { written: string[] }
+/** Build-time prerendering (SSG): write HTML + /_data payloads under `<buildDir>/client/_prerender/`. */
+export declare function runPrerender(options: PrerenderOptions): Promise<PrerenderResult>;
+/** Render the SPA-mode document shell (config `ssr: false`). */
+export declare function renderSpaShell(
+  appDir: string,
+  manifest: ServerManifest,
+  registry?: ModuleRegistry,
+): Promise<string>;