@bractjs/bractjs 0.1.27 → 0.1.29

package/src/server/loader.ts

@@ -21,6 +21,7 @@ export async function safeRun<T>(
   fn: ((args: LoaderArgs) => Promise<T> | T) | undefined,
   args: LoaderArgs,
   onError?: OnErrorHook,
+  where?: string,
 ): Promise<T | { __error: unknown } | null> {
   if (!fn) return null;
 
@@ -36,12 +37,14 @@ export async function safeRun<T>(
     // dev we surface the real message + stack for DX. Routes wanting to
     // surface structured user-facing errors should throw an HttpError, not
     // a custom Error subclass.
-    console.error("[bractjs] loader error:", err);
+    // Name the failing module so the log/overlay points at the right file.
+    console.error(`[bractjs] loader error${where ? ` in ${where}` : ""}:`, err);
     await fireOnError(onError, err, args.request);
     const safe = isExplicitDev()
       ? {
           message: err instanceof Error ? err.message : String(err),
           stack: err instanceof Error ? err.stack : undefined,
+          routeFile: where,
         }
       : { message: "Internal Server Error" };
     return { __error: safe };
@@ -60,7 +63,7 @@ export async function runBeforeLoad(
   args: LoaderArgs,
 ): Promise<Response | null> {
   const fn = routeModule.beforeLoad as
-    | ((a: { params: Record<string,string>; context: Record<string,unknown>; location: { pathname: string; search: string } }) => unknown)
+    | ((a: { params: Record<string,string>; context: Record<string,unknown>; location: { pathname: string; search: string }; search?: Record<string, unknown> }) => unknown)
     | undefined;
   if (!fn) return null;
   const url = new URL(args.request.url);
@@ -68,6 +71,7 @@ export async function runBeforeLoad(
     params: args.params,
     context: args.context,
     location: { pathname: url.pathname, search: url.search },
+    search: args.search,
   });
   if (result instanceof Response) return result;
   return null;
@@ -83,13 +87,14 @@ export async function runLoaders(
   // Run every loader in the chain concurrently — root, all layouts, and the
   // route loader. The route loader is usually the slowest and most important
   // one, so it must not be serialized behind the layout wave.
-  const layoutLoaders = chain.layouts.map((mod) =>
-    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError)
+  const files = chain.files;
+  const layoutLoaders = chain.layouts.map((mod, i) =>
+    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.layouts[i])
   );
 
   const [root, route, ...layoutResults] = await Promise.all([
-    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
-    safeRun(chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
+    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.root),
+    safeRun(chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.route),
     ...layoutLoaders,
   ]);
 
@@ -118,9 +123,10 @@ export async function runAction(
 export function buildLoaderArgs(
   request: Request,
   params: Record<string, string>,
-  context: Record<string, unknown>
+  context: Record<string, unknown>,
+  search: Record<string, unknown> = {},
 ): LoaderArgs {
-  return { request, params, context };
+  return { request, params, context, search };
 }
 
 // ── runRouteContext ────────────────────────────────────────────────────────

package/src/server/matcher.ts

@@ -5,6 +5,13 @@ import type { RouteFile, Segment } from "./scanner.ts";
 export interface TrieNode {
   children: Map<string, TrieNode>;
   paramChild?: { name: string; node: TrieNode };
+  /**
+   * An optional param segment (`[[id]]`). When present it behaves like a param
+   * child (binds `name` to the consumed part); the matcher additionally tries
+   * skipping it entirely, so the route at `node` matches with the segment
+   * absent too (the param is then simply not set).
+   */
+  optionalChild?: { name: string; node: TrieNode };
   catchAllChild?: { name: string; node: TrieNode };
   routeFile?: RouteFile;
 }
@@ -33,6 +40,9 @@ export function buildTrie(routes: RouteFile[]): TrieNode {
       } else if ("param" in seg) {
         if (!node.paramChild) node.paramChild = { name: seg.param, node: makeNode() };
         node = node.paramChild.node;
+      } else if ("optional" in seg) {
+        if (!node.optionalChild) node.optionalChild = { name: seg.optional, node: makeNode() };
+        node = node.optionalChild.node;
       } else {
         // catchAll — terminal, store and stop
         if (!node.catchAllChild) node.catchAllChild = { name: seg.catchAll, node: makeNode() };
@@ -62,7 +72,13 @@ function walk(
 ): MatchResult {
   // All parts consumed — check for route at this node
   if (idx === parts.length) {
-    return node.routeFile ? { routeFile: node.routeFile, params } : null;
+    if (node.routeFile) return { routeFile: node.routeFile, params };
+    // An optional param's segment was omitted (e.g. /users for [[id]]). The
+    // route lives one node deeper; the param is simply left unset.
+    if (node.optionalChild?.node.routeFile) {
+      return { routeFile: node.optionalChild.node.routeFile, params };
+    }
+    return null;
   }
 
   const part = parts[idx];
@@ -83,7 +99,18 @@ function walk(
     if (result) return result;
   }
 
-  // 3. Try catch-all — consumes remaining segments
+  // 3. Try optional param — consume this part as the param (the "present"
+  //    case). The "absent" case is handled at the all-parts-consumed branch
+  //    above. Param-before-catch-all keeps optional more specific than splat.
+  if (node.optionalChild) {
+    const result = walk(node.optionalChild.node, parts, idx + 1, {
+      ...params,
+      [node.optionalChild.name]: part,
+    });
+    if (result) return result;
+  }
+
+  // 4. Try catch-all — consumes remaining segments
   if (node.catchAllChild) {
     const remaining = parts.slice(idx).join("/");
     const catchNode = node.catchAllChild.node;

package/src/server/matches.ts

@@ -0,0 +1,50 @@
+import type { LayoutChain } from "./layout.ts";
+import type { LoaderResults } from "./loader.ts";
+import type { RouteMatch } from "../shared/route-types.ts";
+
+/**
+ * Build the `useMatches()` payload: one entry per module in the chain
+ * (root → layouts → route), pairing each module's static `handle` export with
+ * its loader-data slice. Serialized into the SSR bootstrap and `/_data` so the
+ * client can read it without re-importing every module.
+ *
+ * `handle` must be JSON-serializable to survive the SSR/soft-nav transport —
+ * the same constraint loader data already has.
+ */
+export function buildMatches(
+  chain: LayoutChain,
+  loaderData: LoaderResults,
+  params: Record<string, string>,
+  pathname: string,
+): RouteMatch[] {
+  const matches: RouteMatch[] = [];
+  const files = chain.files;
+
+  matches.push({
+    id: files?.root ?? "root",
+    pathname,
+    params,
+    data: loaderData.root,
+    handle: chain.root.handle,
+  });
+
+  chain.layouts.forEach((mod, i) => {
+    matches.push({
+      id: files?.layouts?.[i] ?? `layout:${i}`,
+      pathname,
+      params,
+      data: loaderData.layouts[i] ?? null,
+      handle: mod.handle,
+    });
+  });
+
+  matches.push({
+    id: files?.route ?? "route",
+    pathname,
+    params,
+    data: loaderData.route,
+    handle: chain.route.handle,
+  });
+
+  return matches;
+}

package/src/server/middleware.ts

@@ -22,6 +22,13 @@ export class MiddlewarePipeline {
     return this;
   }
 
+  /** Remove all registered middleware. Useful for tests and for embedders that
+   * rebuild the pipeline (e.g. on a hot reload). */
+  clear(): this {
+    this.fns = [];
+    return this;
+  }
+
   /**
    * Compose all registered middleware into a single chain and execute it.
    * Each fn calls `next()` to invoke the next fn; the last `next()` calls `handler`.
@@ -49,3 +56,62 @@ export class MiddlewarePipeline {
 
 /** Module-level default pipeline — attach middleware here via pipeline.use(). */
 export const pipeline = new MiddlewarePipeline();
+
+// ── Per-route (nested) middleware ────────────────────────────────────────────
+
+/**
+ * A route/layout/root module's `middleware` entry. Same shape as the global
+ * {@link MiddlewareFn}: call `next()` to continue the chain, or return a
+ * `Response` to short-circuit (auth gate, redirect). The `ctx.context` object
+ * is shared and mutable — set fields on it and downstream middleware, loaders,
+ * and actions see them.
+ */
+export type RouteMiddleware = MiddlewareFn;
+
+/**
+ * Compose a route's nested middleware chain (root → layouts → route, in that
+ * order) around `handler` and run it. Mirrors {@link MiddlewarePipeline.run}
+ * but for an ad-hoc, per-request list rather than the module-level pipeline.
+ * An empty list calls `handler` directly (zero overhead for routes that don't
+ * use middleware).
+ */
+export function runRouteMiddleware(
+  fns: RouteMiddleware[],
+  ctx: MiddlewareContext,
+  handler: () => Promise<Response>,
+): Promise<Response> {
+  if (fns.length === 0) return handler();
+  let lastCalled = -1;
+  const dispatch = (i: number): Promise<Response> => {
+    if (i <= lastCalled) {
+      return Promise.reject(new Error("route middleware: next() called more than once"));
+    }
+    lastCalled = i;
+    if (i >= fns.length) return handler();
+    return fns[i](ctx, () => dispatch(i + 1));
+  };
+  return dispatch(0);
+}
+
+/**
+ * Flatten a route chain's `middleware` exports into a single ordered list:
+ * root first, then each layout outermost→innermost, then the leaf route. Each
+ * module may export `middleware` as a single fn or an array; both normalize
+ * here. Non-function entries are ignored defensively.
+ */
+export function collectRouteMiddleware(chain: {
+  root: { middleware?: unknown };
+  layouts: Array<{ middleware?: unknown }>;
+  route: { middleware?: unknown };
+}): RouteMiddleware[] {
+  const out: RouteMiddleware[] = [];
+  const add = (m: unknown) => {
+    if (!m) return;
+    const list = Array.isArray(m) ? m : [m];
+    for (const fn of list) if (typeof fn === "function") out.push(fn as RouteMiddleware);
+  };
+  add(chain.root.middleware);
+  for (const layout of chain.layouts) add(layout.middleware);
+  add(chain.route.middleware);
+  return out;
+}

package/src/server/proto-guard.ts

@@ -0,0 +1,56 @@
+/**
+ * Prototype-pollution guards, shared across every untrusted-object boundary
+ * (server actions, typed /api JSON, form/search → object conversions).
+ *
+ * Two strategies, used where each fits:
+ *
+ *  1. {@link hasForbiddenKey} — a deep scan that REJECTS a parsed JSON value
+ *     carrying a dangerous key. Used on /_action and /api JSON bodies, where a
+ *     400 is the right UX and the payload shape is the app's contract.
+ *
+ *  2. {@link nullProtoFromEntries} — builds a null-prototype object from
+ *     key/value pairs so a key literally named "__proto__" becomes an ordinary
+ *     own property that can never reach Object.prototype. Used for the
+ *     FormData / URLSearchParams → object conversions, which must accept
+ *     arbitrary field names without erroring.
+ */
+
+// `__proto__` is the actual pollution vector for own-keys produced by
+// JSON.parse. `constructor`/`prototype` are included defensively: a recursive
+// merge that walks `obj.constructor.prototype` can be steered by them too.
+const FORBIDDEN_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+
+// Max nesting we will fully scan. Legitimate payloads are shallow; anything
+// deeper is treated as hostile and rejected (fail closed) — see hasForbiddenKey.
+const MAX_SCAN_DEPTH = 200;
+
+/**
+ * Deep scan for a forbidden key anywhere in a parsed JSON value.
+ *
+ * SECURITY(high): this is a security filter, so it FAILS CLOSED. A value nested
+ * past MAX_SCAN_DEPTH returns `true` (rejected) rather than being passed
+ * through — otherwise an attacker could bury `__proto__` below the cap to evade
+ * the check and reach a recursive-merge sink in handler code.
+ */
+export 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;
+}
+
+/**
+ * Build a null-prototype object from [key, value] entries. A key named
+ * "__proto__" lands as a plain own property instead of mutating the prototype,
+ * so downstream spreads/merges of the result are pollution-safe.
+ */
+export function nullProtoFromEntries<V>(
+  entries: Iterable<readonly [string, V]>,
+): Record<string, V> {
+  const out = Object.create(null) as Record<string, V>;
+  for (const [k, v] of entries) out[k] = v;
+  return out;
+}

package/src/server/render.ts

@@ -1,7 +1,7 @@
 import { renderToReadableStream } from "react-dom/server";
 import { createElement, Fragment, type ReactNode } from "react";
-import type { MetaDescriptor } from "../shared/route-types.ts";
-import { safeStringify, isDevRuntime } from "./env.ts";
+import type { MetaDescriptor, RouteMatch } from "../shared/route-types.ts";
+import { safeStringify, isDevRuntime, getDevHmrPort } from "./env.ts";
 import { errorOverlayScript } from "../dev/error-overlay.ts";
 import { mergeMeta } from "./meta.ts";
 import { MetaTags } from "../shared/meta-tags.tsx";
@@ -18,13 +18,29 @@ export interface RenderOptions {
   actionData: unknown;
   params: Record<string, string>;
   pathname: string;
+  /** Validated search params — hydrates `useSearch()` so the client never re-validates. */
+  search?: Record<string, unknown>;
   manifest: ServerManifest;
   meta: MetaDescriptor[];
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches?: RouteMatch[];
   status?: number;
   /** Path of the matched route file (e.g. "routes/_index.tsx"), used by the client to pre-import the module before hydration. */
   routeFile?: string;
   /** Per-request CSP nonce (set by the opt-in `csp()` middleware). Applied to the inline bootstrap script + client entry module tags. */
   nonce?: string;
+  /**
+   * Set when the document did NOT SSR the route component: the client renders
+   * the Fallback during hydration, then swaps in the real component
+   * ("data-only": data already present; "client-only": after a /_data fetch;
+   * "spa": static shell, everything resolved client-side).
+   */
+  ssrMode?: "client-only" | "data-only" | "spa";
+  /**
+   * Resolved route `headers()` output (root → layout → route merged). Applied
+   * on top of the baseline document headers, overriding any same-key default.
+   */
+  headers?: Headers | null;
 }
 
 export async function renderRoute(options: RenderOptions): Promise<Response> {
@@ -38,13 +54,19 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
     status = 200,
   } = options;
 
-  const devFlag = isDevRuntime() ? "window.__BRACT_DEV__=true;" : "";
+  // In dev, publish the HMR port so the injected client connects to the
+  // configured `hmrPort` rather than a hardcoded 3001. 0 → omit (client
+  // defaults to 3001).
+  const hmrPort = isDevRuntime() ? getDevHmrPort() : 0;
+  const devFlag = isDevRuntime()
+    ? "window.__BRACT_DEV__=true;" + (hmrPort ? `window.__BRACTJS_HMR_PORT__=${hmrPort};` : "")
+    : "";
   const devOverlay = isDevRuntime() ? devFlag + errorOverlayScript + "\n" : "";
   const mergedMeta = mergeMeta(options.meta ?? []);
   // The merged descriptor array is what the client reads to keep the document
   // head in sync on soft navigation — keep it shaped, not stringified HTML.
   const bootstrapScriptContent =
-    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, manifest, routeFile: options.routeFile, meta: mergedMeta })};`;
+    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, search: options.search, manifest, routeFile: options.routeFile, meta: mergedMeta, matches: options.matches, ssrMode: options.ssrMode })};`;
 
   // Render <title>/<meta> elements alongside the app shell. React 19 hoists
   // document-metadata elements into <head> during streaming SSR, so crawlers
@@ -75,19 +97,30 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
 
   const responseStatus = renderError ? 500 : status;
 
-  return new Response(stream, {
-    status: responseStatus,
-    headers: {
-      "Content-Type": "text/html; charset=utf-8",
-      "Transfer-Encoding": "chunked",
-      // SECURITY(medium): baseline hardening headers. For a Content-Security-
-      // Policy, opt into the nonce-based `csp()` middleware — it generates a
-      // per-request nonce, applies it to the inline bootstrap script + client
-      // entry module here (via renderToReadableStream's `nonce` option), and
-      // sets the CSP response header.
-      "X-Content-Type-Options": "nosniff",
-      "X-Frame-Options": "SAMEORIGIN",
-      "Referrer-Policy": "strict-origin-when-cross-origin",
-    },
+  const headers = new Headers({
+    "Content-Type": "text/html; charset=utf-8",
+    "Transfer-Encoding": "chunked",
+    // SECURITY(medium): baseline hardening headers. For a Content-Security-
+    // Policy, opt into the nonce-based `csp()` middleware — it generates a
+    // per-request nonce, applies it to the inline bootstrap script + client
+    // entry module here (via renderToReadableStream's `nonce` option), and
+    // sets the CSP response header.
+    "X-Content-Type-Options": "nosniff",
+    "X-Frame-Options": "SAMEORIGIN",
+    "Referrer-Policy": "strict-origin-when-cross-origin",
   });
+
+  // Route `headers()` output (root → layout → route) overrides the baseline.
+  // Content-Type / Transfer-Encoding stay framework-owned: a route shouldn't
+  // be able to corrupt the streamed document envelope. Don't apply on render
+  // errors — that path serves a generic 500, not the route's cached document.
+  if (options.headers && !renderError) {
+    options.headers.forEach((value, key) => {
+      const k = key.toLowerCase();
+      if (k === "content-type" || k === "transfer-encoding") return;
+      headers.set(key, value);
+    });
+  }
+
+  return new Response(stream, { status: responseStatus, headers });
 }

package/src/server/request-handler.ts

@@ -3,14 +3,17 @@ import type { TrieNode } from "./matcher.ts";
 import { matchRoute } from "./matcher.ts";
 import { resolveRouteChain, type ModuleRegistry } from "./layout.ts";
 import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad } from "./loader.ts";
+import { validateSearch } from "./search.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
-import { resolveMeta } from "./meta.ts";
+import { resolveMeta, mergeMeta } from "./meta.ts";
+import { resolveHeaders } from "./headers.ts";
+import { buildMatches } from "./matches.ts";
 import { json, error, sanitizeRedirect } from "./response.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
 import { isExplicitDev } from "./env.ts";
-import { pipeline, type MiddlewareContext } from "./middleware.ts";
+import { runRouteMiddleware, collectRouteMiddleware, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
-import { isAllowedMutation } from "./csrf.ts";
+import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.ts";
 import { getCspNonce } from "./csp.ts";
 import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
@@ -37,15 +40,15 @@ const MAX_FORM_BYTES = 10 * 1_048_576; // 10 MiB
 export async function handleRequest(
   request: Request,
   trie: TrieNode,
-  config: HandlerConfig
+  config: HandlerConfig,
+  context: Record<string, unknown> = {},
 ): Promise<Response> {
-  const ctx: MiddlewareContext = {
-    request,
-    params: {},
-    context: {},
-  };
-
-  return pipeline.run(ctx, () => route(request, trie, config, ctx.context));
+  // The global pipeline is run once by buildFetchHandler around the whole
+  // dispatch (so it also covers /api, /_action, /_stream, /_image, static).
+  // We receive the shared, already-running `context` here and only run the
+  // per-route (nested) middleware chain — running the global pipeline again
+  // would double-invoke cors()/csp()/etc. for SSR documents.
+  return route(request, trie, config, context);
 }
 
 async function route(
@@ -87,22 +90,51 @@ async function route(
         headers: request.headers,
         method: "GET",
       });
+      // Validate search params before any route work runs — loaders must
+      // never see unvalidated input, and a 400 here is cheaper than a wasted
+      // context-factory/loader run. The thrown 400 Response propagates below.
+      const search = await validateSearch(chain.route.searchSchema, targetUrl);
+
       // SECURITY(high): /_data must run the same auth/redirect gates as a full
       // page request — otherwise a SPA-style soft navigation to a protected
-      // route would bypass beforeLoad() / defineContext() and leak loader data.
-      const routeContext = await runRouteContext(
-        chain.route as Parameters<typeof runRouteContext>[0],
-        loaderRequest,
-        match.params,
-        context,
-      );
-      const args = buildLoaderArgs(loaderRequest, match.params, routeContext);
-      const beforeLoadResponse = await runBeforeLoad(chain.route, args);
-      if (beforeLoadResponse) return beforeLoadResponse;
-      const results = await runLoaders(chain, args, onError);
-      return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
+      // route would bypass nested middleware / beforeLoad() / defineContext()
+      // and leak loader data. Run the route middleware chain around the work,
+      // sharing the same mutable `context` so a gate can set/clear fields.
+      const mwCtx: MiddlewareContext = { request: loaderRequest, params: match.params, context };
+      return runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
+        const routeContext = await runRouteContext(
+          chain.route as Parameters<typeof runRouteContext>[0],
+          loaderRequest,
+          match.params,
+          mwCtx.context,
+        );
+        const args = buildLoaderArgs(loaderRequest, match.params, routeContext, search);
+        const beforeLoadResponse = await runBeforeLoad(chain.route, args);
+        if (beforeLoadResponse) return beforeLoadResponse;
+        const results = await runLoaders(chain, args, onError);
+        // Merged meta must ride along: ClientRouter re-renders the document head
+        // from this payload on soft navigation, and the initial __BRACTJS_DATA__
+        // already carries the merged shape.
+        const meta = mergeMeta(resolveMeta(chain, results, match.params));
+        const matches = buildMatches(chain, results, match.params, targetPathname);
+        const dataRes = json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params, meta, search, matches });
+        // Apply the route `headers()` chain so a soft navigation gets the same
+        // Cache-Control/ETag/Vary as the full document load (renderRoute applies
+        // them there). Content-Type stays application/json.
+        const dataHeaders = resolveHeaders(chain, results, match.params, loaderRequest);
+        if (dataHeaders) {
+          dataHeaders.forEach((value, key) => {
+            if (key.toLowerCase() === "content-type") return;
+            dataRes.headers.set(key, value);
+          });
+        }
+        return dataRes;
+      });
     } catch (err) {
       if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
+      // A non-redirect Response (e.g. the 400 thrown by search validation)
+      // is the intended reply — pass it through verbatim.
+      if (err instanceof Response) return err;
       if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
       await fireOnError(onError, err, request);
@@ -115,14 +147,32 @@ async function route(
   if (!match) return error("Not Found", 404);
 
   const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
+
+  // Validate search params before any route work (context factory, beforeLoad,
+  // action, loaders) — they all receive the validated object.
+  let search: Record<string, unknown>;
+  try {
+    search = await validateSearch(chain.route.searchSchema, url);
+  } catch (err) {
+    if (err instanceof Response) return err;
+    throw err;
+  }
+
+  // Nested route middleware (root → layout → route) wraps the action, loaders,
+  // and render. It shares the same mutable `context` object, runs *inside* the
+  // global pipeline, and can short-circuit (auth gate / redirect) by returning
+  // a Response. Empty chains call the work directly (no overhead).
+  const mwCtx: MiddlewareContext = { request, params: match.params, context };
+  return runRouteMiddleware(collectRouteMiddleware(chain), mwCtx, async () => {
+
   // Run per-route context factory (defineContext export) before loaders.
   const routeContext = await runRouteContext(
     chain.route as Parameters<typeof runRouteContext>[0],
     request,
     match.params,
-    context,
+    mwCtx.context,
   );
-  const args = buildLoaderArgs(request, match.params, routeContext);
+  const args = buildLoaderArgs(request, match.params, routeContext, search);
 
   // ── beforeLoad ────────────────────────────────────────────────────────
   const beforeLoadResponse = await runBeforeLoad(chain.route, args);
@@ -131,7 +181,7 @@ async function route(
   // ── Action (mutating methods) ─────────────────────────────────────────
   let actionData: unknown = null;
   if (MUTATING_METHODS.has(request.method)) {
-    if (!isAllowedMutation(request)) return error("Forbidden", 403);
+    if (!isAllowedMutation(request)) return csrfForbiddenResponse();
     // Reject up front if the client advertises an oversized body.
     const clRaw = request.headers.get("Content-Length");
     if (clRaw) {
@@ -148,6 +198,8 @@ async function route(
     } catch (err) {
       if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
       if (isHttpError(err)) return error(err.message, err.status);
+      // Name the failing route so the log points at the right file.
+      console.error(`[bractjs] action error in ${chain.files?.route ?? match.routeFile.filePath}:`, err);
       await fireOnError(onError, err, request);
       if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
@@ -167,10 +219,20 @@ async function route(
     }
   }
 
+  // ── Selective SSR ─────────────────────────────────────────────────────
+  // `ssr: false` skips the ROUTE loader during document SSR (root/layout
+  // loaders still run — they render the shell). beforeLoad already ran above:
+  // it is the auth gate and must hold for every mode. The client completes
+  // the render via /_data after hydration, where the loader DOES run.
+  const routeSsr = chain.route.ssr ?? true;
+  const loaderChain = routeSsr === false
+    ? { ...chain, route: { ...chain.route, loader: undefined } }
+    : chain;
+
   // ── Loaders ───────────────────────────────────────────────────────────
   let loaderResults;
   try {
-    loaderResults = await runLoaders(chain, args, onError);
+    loaderResults = await runLoaders(loaderChain, args, onError);
   } catch (err) {
     if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
     if (isHttpError(err)) return error(err.message, err.status);
@@ -187,7 +249,14 @@ async function route(
 
   // ── SSR render ────────────────────────────────────────────────────────
   const RootComponent = chain.root.default ?? (() => null);
-  const RouteComponent = chain.route.default;
+  // Non-default SSR modes render the Fallback (or nothing) in the component's
+  // place; the client swaps in the real component after hydration.
+  const RouteComponent = routeSsr === true ? chain.route.default : chain.route.Fallback;
+  const ssrMode = routeSsr === true ? undefined : routeSsr === false ? "client-only" as const : "data-only" as const;
+
+  // useMatches() payload — the chain's handle + data, for breadcrumbs etc.
+  // Built from loaderChain so the loader slices line up with what ran.
+  const matches = buildMatches(loaderChain, loaderResults, match.params, pathname);
 
   // Wrap root in BractJSProvider so <Outlet> can render the route component
   // server-side without needing a ClientRouter.
@@ -201,12 +270,19 @@ async function route(
         pathname,
         manifest: manifest as unknown as import("../shared/context.ts").RouteManifest,
         RouteComponent,
+        location: { pathname, search: url.search, hash: "", state: null, key: "default" },
+        search,
+        matches,
       },
       children: createElement(RootComponent),
     },
   );
 
   const meta = resolveMeta(chain, loaderResults, match.params);
+  // Route `headers()` chain (Cache-Control/ETag/Vary/…), applied on top of the
+  // baseline document headers in renderRoute. Uses the loaders that actually
+  // ran (loaderChain) so a selective-SSR route's headers() sees the same data.
+  const routeHeaders = resolveHeaders(loaderChain, loaderResults, match.params, request);
 
   return renderRoute({
     shell,
@@ -214,10 +290,16 @@ async function route(
     actionData,
     params: match.params,
     pathname,
+    search,
     manifest,
     meta,
+    matches,
+    headers: routeHeaders,
     routeFile: match.routeFile.filePath,
     // Set by the opt-in csp() middleware; undefined otherwise.
-    nonce: getCspNonce(context),
+    nonce: getCspNonce(mwCtx.context),
+    ssrMode,
+  });
+
   });
 }