@bractjs/bractjs 0.1.28 → 0.1.29

package/src/__tests__/use-matches.test.ts

@@ -0,0 +1,54 @@
+import { test, expect, describe } from "bun:test";
+import { buildMatches } from "../server/matches.ts";
+import type { LayoutChain } from "../server/layout.ts";
+import type { LoaderResults } from "../server/loader.ts";
+
+describe("buildMatches", () => {
+  test("returns root → layouts → route in order with ids and data", () => {
+    const chain: LayoutChain = {
+      root: { handle: { breadcrumb: "Home" } },
+      layouts: [{ handle: { breadcrumb: "Blog" } }],
+      route: { handle: { breadcrumb: "Post" } },
+      files: { root: "root.tsx", layouts: ["routes/blog/layout.tsx"], route: "routes/blog/[id].tsx" },
+    };
+    const data: LoaderResults = { root: { user: "a" }, layouts: [{ posts: 2 }], route: { id: "7" } };
+
+    const matches = buildMatches(chain, data, { id: "7" }, "/blog/7");
+
+    expect(matches.map((m) => m.id)).toEqual([
+      "root.tsx",
+      "routes/blog/layout.tsx",
+      "routes/blog/[id].tsx",
+    ]);
+    expect(matches.map((m) => m.handle?.breadcrumb)).toEqual(["Home", "Blog", "Post"]);
+    expect(matches[2].data).toEqual({ id: "7" });
+    expect(matches[1].data).toEqual({ posts: 2 });
+    // params + pathname shared across the chain.
+    expect(matches.every((m) => m.pathname === "/blog/7")).toBe(true);
+    expect(matches.every((m) => m.params.id === "7")).toBe(true);
+  });
+
+  test("handle is undefined when a module does not export it", () => {
+    const chain: LayoutChain = {
+      root: {},
+      layouts: [],
+      route: { handle: { title: "x" } },
+      files: { root: "root.tsx", layouts: [], route: "routes/_index.tsx" },
+    };
+    const data: LoaderResults = { root: null, layouts: [], route: null };
+    const matches = buildMatches(chain, data, {}, "/");
+    expect(matches[0].handle).toBeUndefined();
+    expect(matches[1].handle).toEqual({ title: "x" });
+  });
+
+  test("falls back to synthetic ids when files metadata is absent", () => {
+    const chain: LayoutChain = {
+      root: {},
+      layouts: [{}],
+      route: {},
+    };
+    const data: LoaderResults = { root: null, layouts: [null], route: null };
+    const matches = buildMatches(chain, data, {}, "/x");
+    expect(matches.map((m) => m.id)).toEqual(["root", "layout:0", "route"]);
+  });
+});

package/src/build/route-lint.ts

@@ -4,9 +4,9 @@ import { extractExports } from "./directives.ts";
 // (wrong case) of one of these is almost always a mistake — the framework's
 // projection is case-sensitive, so `Loader` is silently ignored.
 export const ROUTE_EXPORT_NAMES = [
-  "default", "loader", "action", "meta", "beforeLoad", "shouldRevalidate",
-  "searchSchema", "ssr", "Fallback", "handle", "ErrorBoundary", "config",
-  "loaderDeps", "context",
+  "default", "loader", "action", "clientLoader", "clientAction", "meta", "headers",
+  "middleware", "beforeLoad", "shouldRevalidate", "searchSchema", "ssr", "Fallback",
+  "handle", "ErrorBoundary", "config", "loaderDeps", "context",
 ] as const;
 
 const CANONICAL_LOWER = new Map(ROUTE_EXPORT_NAMES.map((n) => [n.toLowerCase(), n]));

package/src/client/ClientRouter.tsx

@@ -16,7 +16,7 @@ import { matchPatternForPath, toSamePath, parseTo, createLocationKey } from "./n
 import { loaderCache, cacheKey } from "./cache.ts";
 import { registerRevalidator, type RevalidationInfo } from "./revalidation.ts";
 import { MetaTags } from "../shared/meta-tags.tsx";
-import type { MetaDescriptor, RouterLocation, ShouldRevalidateFunction } from "../shared/route-types.ts";
+import type { MetaDescriptor, RouterLocation, RouteMatch, ShouldRevalidateFunction } from "../shared/route-types.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -47,6 +47,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   const [params, setParams] = useState(initialData.params);
   const [location, setLocation] = useState<RouterLocation>(initialData.location);
   const [search, setSearch] = useState<Record<string, unknown>>(initialData.search ?? {});
+  const [matches, setMatches] = useState<RouteMatch[]>(initialData.matches ?? []);
   const [navState, setNavState] = useState<NavigationState>("idle");
   const [revalidationState, setRevalidationState] = useState<"idle" | "loading">("idle");
   const [currentModule, setCurrentModule] = useState<RouteModuleClient | null>(initialModule);
@@ -61,6 +62,8 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   // Refs mirroring state that the stable revalidate/submit callbacks need.
   const locationRef = useRef(location);
   useEffect(() => { locationRef.current = location; }, [location]);
+  const paramsRef = useRef(params);
+  useEffect(() => { paramsRef.current = params; }, [params]);
   const currentModuleRef = useRef(currentModule);
   useEffect(() => { currentModuleRef.current = currentModule; }, [currentModule]);
 
@@ -69,6 +72,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     if (state.actionData !== undefined) setActionData(state.actionData);
     if (state.params !== undefined) setParams(state.params);
     if (state.search !== undefined) setSearch(state.search);
+    if (state.matches !== undefined) setMatches(state.matches);
     if (state.location !== undefined) setLocation(state.location);
     else if (state.pathname !== undefined) {
       // Legacy callers pass a (possibly query-carrying) pathname string.
@@ -148,6 +152,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
           // React 19 hoists the <title>/<meta> elements rendered by <MetaTags>
           // into <head>, so description/OG tags update on soft navigation.
           setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+          setMatches((data.matches as RouteMatch[] | undefined) ?? []);
         });
       };
 
@@ -199,6 +204,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
               setParams(((fresh as Record<string, unknown>).params as Record<string, string>) ?? {});
               setSearch(((fresh as Record<string, unknown>).search as Record<string, unknown>) ?? {});
               setMeta(((fresh as Record<string, unknown>).meta as MetaDescriptor[] | undefined) ?? []);
+              setMatches(((fresh as Record<string, unknown>).matches as RouteMatch[] | undefined) ?? []);
             });
           });
         return;
@@ -215,6 +221,27 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         return;
       }
       const data = await res.json() as Record<string, unknown>;
+
+      // clientLoader (RR7-style): when the route exports one, it runs in the
+      // browser and its result replaces the route's loader slice. It receives a
+      // `serverLoader()` that resolves to the freshly-fetched server data, so a
+      // clientLoader can wrap/augment/cache it. Other slices (root/layouts) and
+      // the meta/matches payload are untouched.
+      const clientLoader = (routeModule as Record<string, unknown> | null)
+        ?.clientLoader as import("../shared/route-types.ts").ClientLoaderFunction | undefined;
+      if (typeof clientLoader === "function") {
+        try {
+          data.route = await clientLoader({
+            request: new Request(new URL(dataPath, window.location.origin)),
+            params: (data.params as Record<string, string>) ?? {},
+            search: (data.search as Record<string, unknown>) ?? {},
+            serverLoader: () => Promise.resolve(data.route),
+          });
+        } catch (err) {
+          console.error("[bractjs] clientLoader error:", err);
+        }
+      }
+
       if (staleTime > 0) loaderCache.set(key, data, staleTime, gcTime);
 
       // Update DevTools state (dev-only — no-op in prod since the import fails).
@@ -290,6 +317,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         setParams((data.params as Record<string, string>) ?? {});
         setSearch((data.search as Record<string, unknown>) ?? {});
         setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+        setMatches((data.matches as RouteMatch[] | undefined) ?? []);
       });
     } catch (err) {
       console.error("[bractjs] revalidate error:", err);
@@ -304,6 +332,39 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
     return () => registerRevalidator(null);
   }, [revalidate]);
 
+  // clientLoader.hydrate: for a fully-SSR'd route whose clientLoader opted into
+  // hydration, run it once after mount and replace the route's loader slice.
+  // Routes that didn't SSR (hydrationPending truthy) take the fetch path below,
+  // where clientLoader already applies via loadRoute on navigation; this effect
+  // is only for the first paint of an SSR document.
+  useEffect(() => {
+    if (hydrationPending) return;
+    const cl = (initialModule as Record<string, unknown> | null)
+      ?.clientLoader as import("../shared/route-types.ts").ClientLoaderFunction | undefined;
+    if (typeof cl !== "function" || cl.hydrate !== true) return;
+    let cancelled = false;
+    void (async () => {
+      const path = window.location.pathname + window.location.search;
+      const serverSlice = (initialData.loaderData as Record<string, unknown>)?.route;
+      try {
+        const next = await cl({
+          request: new Request(new URL(path, window.location.origin)),
+          params: initialData.params,
+          search: initialData.search ?? {},
+          serverLoader: async () => serverSlice,
+        });
+        if (cancelled) return;
+        startTransition(() => {
+          setLoaderData((prev) => ({ ...prev, route: next }));
+        });
+      } catch (err) {
+        console.error("[bractjs] clientLoader (hydrate) error:", err);
+      }
+    })();
+    return () => { cancelled = true; };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
   // Selective-SSR / SPA hydration completion. The first client render matched
   // the server (Fallback or empty shell); after mount, put loader data in
   // place and swap in the real component via a transition.
@@ -334,6 +395,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
             setParams((data.params as Record<string, string>) ?? {});
             setSearch((data.search as Record<string, unknown>) ?? {});
             setMeta((data.meta as MetaDescriptor[] | undefined) ?? []);
+            setMatches((data.matches as RouteMatch[] | undefined) ?? []);
             setHydrationPending(false);
           });
           return;
@@ -402,34 +464,72 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
       const body = opts.body instanceof FormData
         ? opts.body
         : new URLSearchParams(opts.body);
-      const res = await fetch(to, {
-        method: opts.method.toUpperCase(),
-        body,
-        headers: { "X-BractJS-Action": "1" },
-      });
-      if (res.redirected) {
-        const safe = toSamePath(res.url);
-        if (safe) {
-          // navigate() loads fresh data for the target — no extra revalidation.
-          await navigateRef.current(safe);
-          return;
+
+      // The server submit — also the `serverAction()` a clientAction can call.
+      // A redirected response short-circuits to a real navigation (via
+      // toSamePath so an attacker Location can never soft-nav the SPA); it
+      // returns a sentinel so the caller stops.
+      const REDIRECTED = Symbol("redirected");
+      let lastStatus = 0;
+      const doServerPost = async (): Promise<unknown> => {
+        const res = await fetch(to, {
+          method: opts.method.toUpperCase(),
+          body,
+          headers: { "X-BractJS-Action": "1" },
+        });
+        lastStatus = res.status;
+        if (res.redirected) {
+          const safe = toSamePath(res.url);
+          if (safe) { await navigateRef.current(safe); return REDIRECTED; }
+          window.location.assign(res.url);
+          return REDIRECTED;
         }
-        window.location.assign(res.url);
-        return;
+        return res.json();
+      };
+
+      // clientAction (RR7-style): if the target route exports one, it runs in
+      // the browser and decides whether/how to hit the server via serverAction().
+      const [toPath] = to.split("?");
+      const pattern = matchPatternForPath(toPath, manifest);
+      const chunkUrl = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
+      let clientAction: import("../shared/route-types.ts").ClientActionFunction | undefined;
+      if (chunkUrl) {
+        try {
+          const mod = await import(/* @vite-ignore */ chunkUrl) as Record<string, unknown>;
+          if (typeof mod.clientAction === "function") {
+            clientAction = mod.clientAction as import("../shared/route-types.ts").ClientActionFunction;
+          }
+        } catch { /* fall back to a plain server submit */ }
       }
-      const data = (await res.json()) as unknown;
+
+      let data: unknown;
+      if (clientAction) {
+        let calledServer = false;
+        data = await clientAction({
+          request: new Request(new URL(to, window.location.origin), { method: opts.method.toUpperCase() }),
+          params: paramsRef.current,
+          formData: body instanceof FormData ? body : new FormData(),
+          serverAction: () => { calledServer = true; return doServerPost(); },
+        });
+        // If the clientAction triggered a redirect via serverAction(), stop.
+        if (calledServer && data === REDIRECTED) return;
+      } else {
+        data = await doServerPost();
+        if (data === REDIRECTED) return;
+      }
+
       setActionData(data);
       setNavState("loading");
-      await revalidate({ formMethod: opts.method, actionStatus: res.status });
+      await revalidate({ formMethod: opts.method, actionStatus: lastStatus });
     } finally {
       setNavState("idle");
     }
-  }, [revalidate]);
+  }, [revalidate, manifest]);
 
   return (
     <RouterContext.Provider
       value={{
-        loaderData, actionData, params, pathname: location.pathname, location, search,
+        loaderData, actionData, params, pathname: location.pathname, location, search, matches,
         manifest, currentModule, setRoute, revalidate, revalidationState, hydrationPending,
       }}
     >

package/src/client/hooks/useMatches.ts

@@ -0,0 +1,32 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+import type { RouteMatch } from "../../shared/route-types.ts";
+
+/**
+ * Returns the matched route chain, outermost → innermost: the root, then each
+ * layout, then the leaf route. Each entry exposes `{ id, pathname, params,
+ * data, handle }`, where `handle` is that module's static `handle` export.
+ *
+ * Use it to build breadcrumbs or conditional chrome from `handle` without
+ * threading props through every layout. Works in both SSR and client contexts;
+ * the chain updates on soft navigation and revalidation.
+ *
+ * ```tsx
+ * // routes/blog/[id].tsx
+ * export const handle = { breadcrumb: "Post" };
+ *
+ * // some layout
+ * const crumbs = useMatches()
+ *   .filter((m) => m.handle?.breadcrumb)
+ *   .map((m) => m.handle!.breadcrumb as string);
+ * ```
+ *
+ * `handle` must be JSON-serializable — it travels in the SSR bootstrap and the
+ * `/_data` soft-nav payload, the same as loader data.
+ */
+export function useMatches(): RouteMatch[] {
+  const router = useContext(RouterContext);
+  const bract = useContext(BractJSContext);
+  return router?.matches ?? bract?.matches ?? [];
+}

package/src/client/router.tsx

@@ -1,6 +1,6 @@
 import { createContext, useContext, type ComponentType } from "react";
 import type { ServerManifest } from "../server/render.ts";
-import type { RouterLocation } from "../shared/route-types.ts";
+import type { RouterLocation, RouteMatch } from "../shared/route-types.ts";
 
 // ── Route module shape visible on the client ───────────────────────────────
 
@@ -9,6 +9,10 @@ export interface RouteModuleClient {
   ErrorBoundary?: ComponentType<{ error: Error }>;
   /** SSR'd placeholder for selective-SSR routes (`ssr: false` / `"data-only"`). */
   Fallback?: ComponentType;
+  /** Browser-side loader (RR7-style). Runs on navigation instead of just fetching /_data. */
+  clientLoader?: import("../shared/route-types.ts").ClientLoaderFunction;
+  /** Browser-side action (RR7-style). Runs on submit instead of POSTing directly. */
+  clientAction?: import("../shared/route-types.ts").ClientActionFunction;
 }
 
 /**
@@ -30,6 +34,8 @@ export interface RouteState {
   location: RouterLocation;
   /** Validated search params (route `searchSchema` output; raw string record otherwise). */
   search: Record<string, unknown>;
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches: RouteMatch[];
 }
 
 export interface RouterContextValue extends RouteState {

package/src/client/rpc.ts

@@ -49,9 +49,19 @@ export function createClient<
             const httpMethod = method.toUpperCase();
             const url = baseUrl + path;
             const hasBody = httpMethod !== "GET" && httpMethod !== "DELETE" && input !== undefined;
+            // Send the custom CSRF marker on every mutating call. The server's
+            // /api CSRF gate accepts Sec-Fetch-Site / Origin too, but this
+            // header keeps same-origin calls working even behind proxies that
+            // strip those — and it can't be set cross-origin without a CORS
+            // preflight the framework's CORS never grants. Mirrors the
+            // server-action proxy in src/build/directives.ts.
+            const isMutating = httpMethod !== "GET";
+            const headers: Record<string, string> = {};
+            if (hasBody) headers["Content-Type"] = "application/json";
+            if (isMutating) headers["X-BractJS-Action"] = "1";
             const res = await fetch(url, {
               method: httpMethod,
-              headers: hasBody ? { "Content-Type": "application/json" } : undefined,
+              headers: Object.keys(headers).length > 0 ? headers : undefined,
               body: hasBody ? JSON.stringify(input) : undefined,
             });
             if (!res.ok) {

package/src/codegen/module-registry.ts

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-import { scanRoutes, type RouteFile } from "../server/scanner.ts";
+import { scanRoutes, layoutDirsFromFilePath, type RouteFile } from "../server/scanner.ts";
 
 // Codegen entry-points: `bun build --compile` can't statically trace
 // `Bun.Glob` scans or `import(absPath)` calls, so we materialise the route /
@@ -9,13 +9,14 @@ import { scanRoutes, type RouteFile } from "../server/scanner.ts";
 
 // ── Path safety ────────────────────────────────────────────────────────────
 
-// Allow ASCII filename characters, `/` for nested directories, and `[`/`]`
-// for file-based dynamic route syntax (`[id]`, `[...slug]`). All emit sites
-// wrap the path in JSON.stringify, but we still allowlist the charset as
-// defense-in-depth against a hostile filename containing a backtick, $, quote,
-// backslash, or whitespace breaking out of the generated literal. `..` as a
-// whole segment is rejected separately below (path-traversal guard).
-const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
+// Allow ASCII filename characters, `/` for nested directories, `[`/`]` for
+// file-based dynamic route syntax (`[id]`, `[...slug]`, `[[id]]`), and `(`/`)`
+// for route-group folders (`(marketing)`). All emit sites wrap the path in
+// JSON.stringify, but we still allowlist the charset as defense-in-depth
+// against a hostile filename containing a backtick, $, quote, backslash, or
+// whitespace breaking out of the generated literal. `..` as a whole segment is
+// rejected separately below (path-traversal guard).
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]()]+$/;
 
 function assertSafeFilePath(filePath: string): void {
   if (!SAFE_FILEPATH_RE.test(filePath)) {
@@ -37,26 +38,17 @@ function pathToIdent(prefix: string, relPath: string): string {
 
 // ── Layout discovery ───────────────────────────────────────────────────────
 
-function layoutDirsForPattern(urlPattern: string): string[] {
-  if (urlPattern === "") return [];
-  const segments = urlPattern.split("/");
-  segments.pop();
-  const dirs: string[] = [];
-  for (let i = 1; i <= segments.length; i++) {
-    dirs.push(segments.slice(0, i).join("/"));
-  }
-  return dirs;
-}
-
 /**
  * Find every `routes/<dir>/layout.tsx` (or `.ts`) that exists on disk for the
  * given set of routes. Mirrors the runtime probe in `resolveLayoutChain` but
- * runs once at codegen time so the generated registry is exhaustive.
+ * runs once at codegen time so the generated registry is exhaustive. Layout
+ * dirs are derived from each route's FILE path (via `layoutDirsFromFilePath`)
+ * so route-group folders are covered identically to the runtime.
  */
 async function collectLayouts(appDir: string, routes: RouteFile[]): Promise<string[]> {
   const layoutPaths = new Set<string>();
   for (const route of routes) {
-    for (const dir of layoutDirsForPattern(route.urlPattern)) {
+    for (const dir of layoutDirsFromFilePath(route.filePath)) {
       for (const ext of ["tsx", "ts"]) {
         const rel = `routes/${dir}/layout.${ext}`;
         const abs = resolve(join(appDir, rel));

package/src/codegen/route-codegen.ts

@@ -3,11 +3,12 @@ import { scanRoutes } from "../server/scanner.ts";
 import type { Segment } from "../server/scanner.ts";
 import { hashString } from "../build/hash.ts";
 
-// Convert [param] / [...catchAll] notation to :param colon-style for URLs.
+// Convert [param] / [[optional]] / [...catchAll] notation to :param colon-style.
 function patternToColon(urlPattern: string): string {
   if (urlPattern === "") return "/";
   return "/" + urlPattern.split("/").map((seg) => {
     if (seg.startsWith("[...") && seg.endsWith("]")) return ":" + seg.slice(4, -1);
+    if (seg.startsWith("[[") && seg.endsWith("]]")) return ":" + seg.slice(2, -2);
     if (seg.startsWith("[") && seg.endsWith("]")) return ":" + seg.slice(1, -1);
     return seg;
   }).join("/");
@@ -16,7 +17,9 @@ function patternToColon(urlPattern: string): string {
 function paramsFromSegments(segments: Segment[]): string[] {
   return segments.flatMap((seg) =>
     typeof seg === "string" ? [] :
-    "param" in seg ? [seg.param] : [seg.catchAll],
+    "param" in seg ? [seg.param] :
+    "optional" in seg ? [seg.optional] :
+    [seg.catchAll],
   );
 }
 
@@ -36,7 +39,9 @@ function substituteParams(pattern: string, params: string[]): string {
 const SAFE_PATTERN_RE = /^\/(?:[A-Za-z0-9_\-]+|:[A-Za-z_][A-Za-z0-9_]*)(?:\/(?:[A-Za-z0-9_\-]+|:[A-Za-z_][A-Za-z0-9_]*))*$|^\/$/;
 const SAFE_IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 // Same guard the module-registry codegen applies before emitting import paths.
-const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
+// Parens are permitted for route-group folders like `(marketing)`; they are
+// inert inside the double-quoted import string the codegen emits.
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]()]+$/;
 
 function assertSafePattern(pattern: string): void {
   if (!SAFE_PATTERN_RE.test(pattern)) {

package/src/config/load.ts

@@ -26,6 +26,7 @@ export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
 
   check("port", typeof c.port === "number" && Number.isFinite(c.port), "a finite number");
   check("hmrPort", typeof c.hmrPort === "number" && Number.isFinite(c.hmrPort), "a finite number");
+  check("maxRequestBodySize", typeof c.maxRequestBodySize === "number" && Number.isFinite(c.maxRequestBodySize) && c.maxRequestBodySize > 0, "a positive finite number");
   check("appDir", typeof c.appDir === "string", "a string");
   check("publicDir", typeof c.publicDir === "string", "a string");
   check("buildDir", typeof c.buildDir === "string", "a string");

package/src/index.ts

@@ -4,9 +4,10 @@ export { buildFetchHandler } from "./server/serve.ts";
 export { defineContext } from "./server/context.ts";
 export type { ContextFactory } from "./server/context.ts";
 export { route } from "./server/api-route.ts";
-export type { ApiRouteDefinition, AppApiRoutes } from "./server/api-route.ts";
+export type { ApiRouteDefinition, ApiRouteOptions, AppApiRoutes } from "./server/api-route.ts";
 export { validate, safeValidate, isValidationResponse, readValidationError } from "./server/validate.ts";
 export type { FieldErrors, ValidationError, SafeValidateResult } from "./server/validate.ts";
+export { hasForbiddenKey, nullProtoFromEntries } from "./server/proto-guard.ts";
 export { formText, formValues } from "./shared/form-data.ts";
 export { defineActions } from "./shared/define-actions.ts";
 export { validateSearch, searchParamsToObject } from "./server/search.ts";
@@ -71,6 +72,12 @@ export type {
   LoaderFunction,
   ActionFunction,
   MetaFunction,
+  HeadersFunction,
+  HeadersArgs,
+  RouteMiddlewareFunction,
+  ClientLoaderFunction,
+  ClientActionFunction,
+  RouteMatch,
   RouteModule,
   RouteDefinition,
   RouterLocation,
@@ -87,8 +94,8 @@ export { BractJSContext, BractJSProvider, useBractJSContext } from "./shared/con
 export type { BractJSContextValue, RouteManifest } from "./shared/context.ts";
 
 // Middleware
-export { pipeline, MiddlewarePipeline } from "./server/middleware.ts";
-export type { MiddlewareFn, MiddlewareContext } from "./server/middleware.ts";
+export { pipeline, MiddlewarePipeline, runRouteMiddleware, collectRouteMiddleware } from "./server/middleware.ts";
+export type { MiddlewareFn, MiddlewareContext, RouteMiddleware } from "./server/middleware.ts";
 export { requestLogger } from "./middleware/requestLogger.ts";
 export { cors } from "./middleware/cors.ts";
 export type { CorsOptions } from "./middleware/cors.ts";
@@ -118,6 +125,7 @@ export { useLoaderData } from "./client/hooks/useLoaderData.ts";
 export { useActionData } from "./client/hooks/useActionData.ts";
 export { useLocation } from "./client/hooks/useLocation.ts";
 export { useParams } from "./client/hooks/useParams.ts";
+export { useMatches } from "./client/hooks/useMatches.ts";
 export { useNavigation } from "./client/hooks/useNavigation.ts";
 export { useNavigate } from "./client/hooks/useNavigate.ts";
 export type { NavigateFn, NavigateOptions } from "./client/hooks/useNavigate.ts";

package/src/server/action-handler.ts

@@ -1,31 +1,12 @@
 import { resolveAction } from "./action-registry.ts";
 import { json } from "./response.ts";
 import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.ts";
+import { hasForbiddenKey } from "./proto-guard.ts";
 
-const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
 // Cap action JSON bodies. Anything over this looks like an abuse attempt;
 // FormData uploads (large files) take the multipart branch and bypass this.
 const MAX_JSON_BODY_BYTES = 1_048_576; // 1 MiB
 
-// Max nesting we will fully scan for forbidden keys. Legitimate action payloads
-// are shallow; anything deeper is treated as hostile.
-const MAX_SCAN_DEPTH = 200;
-
-// Deep scan: nested objects can carry __proto__ pollution vectors too.
-// SECURITY(high): this is a security filter, so it must FAIL CLOSED. A payload
-// nested past MAX_SCAN_DEPTH is rejected (returns true) rather than silently
-// passed — otherwise an attacker could bury `__proto__` below the cap to evade
-// the check and reach a recursive-merge sink in action code.
-function hasForbiddenKey(value: unknown, depth = 0): boolean {
-  if (!value || typeof value !== "object") return false;
-  if (depth > MAX_SCAN_DEPTH) return true;
-  for (const key of Object.keys(value as Record<string, unknown>)) {
-    if (FORBIDDEN_KEYS.has(key)) return true;
-    if (hasForbiddenKey((value as Record<string, unknown>)[key], depth + 1)) return true;
-  }
-  return false;
-}
-
 export async function handleActionRequest(request: Request): Promise<Response | null> {
   const url = new URL(request.url);
   // SECURITY(medium): exact-match prevents URL confusion (e.g. "/_actionfoo"

package/src/server/adapter.ts

@@ -22,9 +22,24 @@ export interface BractAdapter {
  * Default adapter — wraps `Bun.serve()`.
  * Created internally by `createServer()` when no adapter is provided.
  */
+// SECURITY(medium): hard ceiling on request body size at the server boundary,
+// independent of any Content-Length the client advertises. The per-route and
+// /_action handlers apply their own (smaller) caps and double-check the decoded
+// size, but this is the single backstop every code path inherits — it bounds
+// memory even for paths that don't pre-check (e.g. an app's own /api handler
+// that reads request.formData() directly). Sits above the 10 MiB route-form
+// cap so legitimate uploads still pass; raise it via the `maxRequestBodySize`
+// config for apps with a dedicated large-upload endpoint.
+const DEFAULT_MAX_REQUEST_BODY_BYTES = 16 * 1024 * 1024; // 16 MiB
+
 export class BunAdapter implements BractAdapter {
   private server: ReturnType<typeof Bun.serve> | null = null;
   private handler: ((request: Request) => Promise<Response>) | null = null;
+  private maxRequestBodySize: number;
+
+  constructor(maxRequestBodySize: number = DEFAULT_MAX_REQUEST_BODY_BYTES) {
+    this.maxRequestBodySize = maxRequestBodySize;
+  }
 
   setHandler(handler: (request: Request) => Promise<Response>): void {
     this.handler = handler;
@@ -40,6 +55,7 @@ export class BunAdapter implements BractAdapter {
     const handler = this.handler;
     this.server = Bun.serve({
       port,
+      maxRequestBodySize: this.maxRequestBodySize,
       fetch: handler,
       error(err: Error) {
         console.error("[bractjs] unhandled server error:", err);