@bractjs/bractjs 0.1.28 → 0.2.0

package/src/__tests__/scanner.test.ts

@@ -1,5 +1,10 @@
 import { test, expect, describe } from "bun:test";
-import { filePathToPattern, pathToSegments } from "../server/scanner.ts";
+import {
+  filePathToPattern,
+  pathToSegments,
+  layoutDirsFromFilePath,
+  isRouteGroupSegment,
+} from "../server/scanner.ts";
 
 describe("filePathToPattern", () => {
   test("_index maps to empty pattern (root index)", () => {
@@ -25,6 +30,42 @@ describe("filePathToPattern", () => {
   test("strips .ts extension too", () => {
     expect(filePathToPattern("routes/api/data.ts")).toBe("api/data");
   });
+
+  test("route group folder adds no URL segment", () => {
+    expect(filePathToPattern("routes/(marketing)/about.tsx")).toBe("about");
+  });
+
+  test("nested route group strips only the group segment", () => {
+    expect(filePathToPattern("routes/(marketing)/blog/[id].tsx")).toBe("blog/[id]");
+  });
+
+  test("group wrapping the index → root pattern", () => {
+    expect(filePathToPattern("routes/(marketing)/_index.tsx")).toBe("");
+  });
+
+  test("[[id]] optional kept in pattern string", () => {
+    expect(filePathToPattern("routes/users/[[id]].tsx")).toBe("users/[[id]]");
+  });
+});
+
+describe("route groups", () => {
+  test("isRouteGroupSegment detects (group) but not () or plain", () => {
+    expect(isRouteGroupSegment("(marketing)")).toBe(true);
+    expect(isRouteGroupSegment("()")).toBe(false);
+    expect(isRouteGroupSegment("about")).toBe(false);
+    expect(isRouteGroupSegment("[id]")).toBe(false);
+  });
+
+  test("layoutDirsFromFilePath includes group folders", () => {
+    expect(layoutDirsFromFilePath("routes/(marketing)/blog/[id].tsx")).toEqual([
+      "(marketing)",
+      "(marketing)/blog",
+    ]);
+  });
+
+  test("layoutDirsFromFilePath for a top-level route → empty", () => {
+    expect(layoutDirsFromFilePath("routes/about.tsx")).toEqual([]);
+  });
 });
 
 describe("pathToSegments", () => {
@@ -44,6 +85,10 @@ describe("pathToSegments", () => {
     expect(pathToSegments("docs/[...slug]")).toEqual(["docs", { catchAll: "slug" }]);
   });
 
+  test("[[id]] → optional segment", () => {
+    expect(pathToSegments("users/[[id]]")).toEqual(["users", { optional: "id" }]);
+  });
+
   test("nested static path", () => {
     expect(pathToSegments("a/b/c")).toEqual(["a", "b", "c"]);
   });

package/src/__tests__/security-fixes.test.ts

@@ -0,0 +1,201 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { createServer } from "../server/serve.ts";
+import { pipeline } from "../server/middleware.ts";
+import { route, handleApiRequest } from "../server/api-route.ts";
+import { csp } from "../server/csp.ts";
+import { hasForbiddenKey, nullProtoFromEntries } from "../server/proto-guard.ts";
+import { searchParamsToObject } from "../server/search.ts";
+import { validate } from "../server/validate.ts";
+import { resolve } from "node:path";
+
+const PORT = 3989;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+// A marker middleware on the GLOBAL pipeline + a CSP middleware, plus a couple
+// of API routes. Registered before the server starts; cleared afterwards so
+// these don't leak into other suites sharing the process.
+const MARKER = "X-Test-Global-MW";
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  pipeline.clear();
+  pipeline.use(async (_ctx, next) => {
+    const res = await next();
+    res.headers.set(MARKER, "1");
+    return res;
+  });
+  pipeline.use(csp());
+
+  // Protected-by-default mutating route, an opted-out one, and a GET.
+  route("POST", "/api/secure", (input: unknown) => ({ ok: true, input }));
+  route("POST", "/api/public", (input: unknown) => ({ ok: true, input }), { csrf: false });
+  route("GET", "/api/ping", () => ({ pong: true }));
+
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+  pipeline.clear();
+});
+
+// ── H-1 — global middleware now wraps the special endpoints ────────────────
+
+describe("H-1: global middleware covers special endpoints", () => {
+  test("marker + CSP applied to an /api response", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    expect(res.headers.get("Content-Security-Policy")).toContain("default-src 'self'");
+  });
+
+  test("marker applied to /_action (even on 404 unknown id)", async () => {
+    const res = await fetch(`${BASE}/_action?id=deadbeefdeadbeef`, {
+      method: "POST",
+      headers: { "X-BractJS-Action": "1", "Content-Type": "application/json" },
+      body: "[]",
+    });
+    // unknown id → 404, but it still passed through the global pipeline.
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to /_image (even on 400 bad request)", async () => {
+    const res = await fetch(`${BASE}/_image?src=/etc/passwd`);
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to a normal SSR document too (no double-run)", async () => {
+    const res = await fetch(`${BASE}/`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    // CSP header present exactly once.
+    expect(res.headers.get("Content-Security-Policy")).toContain("script-src");
+  });
+});
+
+// ── H-2 — CSRF on typed /api routes ────────────────────────────────────────
+
+describe("H-2: /api CSRF protection", () => {
+  test("cross-site POST to a protected route → 403", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("no-attribution POST (no Origin / no header / no Sec-Fetch-Site) → 403", async () => {
+    // Call the handler directly so no Origin is auto-added by fetch.
+    const req = new Request("http://localhost/api/secure", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    const res = await handleApiRequest(req);
+    expect(res?.status).toBe(403);
+  });
+
+  test("same-origin POST (X-BractJS-Action) to a protected route → 200", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 1 } });
+  });
+
+  test("same-origin POST via Sec-Fetch-Site → 200 (no custom header needed)", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "same-origin" },
+      body: JSON.stringify({ a: 2 }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("opted-out route (csrf:false) allows cross-site POST", async () => {
+    const res = await fetch(`${BASE}/api/public`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 3 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 3 } });
+  });
+
+  test("GET /api is never CSRF-gated", async () => {
+    const res = await fetch(`${BASE}/api/ping`, { headers: { "Sec-Fetch-Site": "cross-site" } });
+    expect(res.status).toBe(200);
+  });
+
+  test("forbidden-key JSON body to an /api route → 400", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: '{"__proto__":{"polluted":true}}',
+    });
+    expect(res.status).toBe(400);
+    // And Object.prototype was not polluted.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+});
+
+// ── M-1 — CSP form-action ──────────────────────────────────────────────────
+
+describe("M-1: CSP defaults", () => {
+  test("default policy includes form-action 'self'", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get("Content-Security-Policy")).toContain("form-action 'self'");
+  });
+});
+
+// ── M-2 — prototype-pollution guards ───────────────────────────────────────
+
+describe("M-2: proto-guard", () => {
+  test("hasForbiddenKey detects buried __proto__", () => {
+    let v: unknown = JSON.parse('{"__proto__":{"x":1}}');
+    for (let i = 0; i < 5; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("hasForbiddenKey passes a clean object", () => {
+    expect(hasForbiddenKey({ a: { b: { c: 1 } } })).toBe(false);
+  });
+
+  test("hasForbiddenKey fails closed past the scan depth", () => {
+    let v: unknown = { value: "x" };
+    for (let i = 0; i < 250; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("searchParamsToObject yields a null-prototype object", () => {
+    const out = searchParamsToObject(new URLSearchParams("__proto__=evil&a=1"));
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    // __proto__ lands as a real own key, not a prototype mutation.
+    expect(out["__proto__"]).toBe("evil");
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+  });
+
+  test("validate() over FormData with a __proto__ field does not pollute", async () => {
+    const fd = new FormData();
+    fd.set("__proto__", "evil");
+    fd.set("name", "ok");
+    // Identity schema — just returns what it gets.
+    const schema = { parse: (x: unknown) => x };
+    const out = (await validate(schema, fd)) as Record<string, unknown>;
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+    expect(out.name).toBe("ok");
+  });
+
+  test("nullProtoFromEntries builds a null-prototype object", () => {
+    const out = nullProtoFromEntries([["__proto__", 1], ["a", 2]]);
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    expect(out["a"]).toBe(2);
+  });
+});

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) {