@bractjs/bractjs 0.1.27 → 0.1.29

package/src/index.ts

@@ -4,9 +4,13 @@ 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 { validate } from "./server/validate.ts";
-export type { FieldErrors, ValidationError } from "./server/validate.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";
 export type { BractAdapter } from "./server/adapter.ts";
 export { BunAdapter } from "./server/adapter.ts";
 
@@ -68,8 +72,19 @@ export type {
   LoaderFunction,
   ActionFunction,
   MetaFunction,
+  HeadersFunction,
+  HeadersArgs,
+  RouteMiddlewareFunction,
+  ClientLoaderFunction,
+  ClientActionFunction,
+  RouteMatch,
   RouteModule,
   RouteDefinition,
+  RouterLocation,
+  ShouldRevalidateArgs,
+  ShouldRevalidateFunction,
+  LoaderData,
+  ActionData,
 } from "./shared/route-types.ts";
 export type { RouteFile, Segment } from "./server/scanner.ts";
 
@@ -79,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";
@@ -102,17 +117,29 @@ export { Form } from "./client/components/Form.tsx";
 export { Await } from "./client/components/Await.tsx";
 export { Image } from "./client/components/Image.tsx";
 export type { ImageProps, ImageFormat, ImageFit } from "./client/components/Image.tsx";
+export { ScrollRestoration } from "./client/components/ScrollRestoration.tsx";
+export type { ScrollRestorationProps } from "./client/components/ScrollRestoration.tsx";
 
 // Client hooks
 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";
 export { useFetcher } from "./client/hooks/useFetcher.ts";
+export type { FetcherResult, FetcherFormProps, UseFetcherOptions } from "./client/hooks/useFetcher.ts";
+export { useFetchers } from "./client/hooks/useFetchers.ts";
+export type { FetcherEntry, FetcherState } from "./client/fetcher-store.ts";
+export { useRevalidator } from "./client/hooks/useRevalidator.ts";
+export type { Revalidator } from "./client/hooks/useRevalidator.ts";
 export { useSearchParams } from "./client/hooks/useSearchParams.ts";
 export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
+export { useSearch, useSetSearch } from "./client/hooks/useSearch.ts";
+export type { SetSearchFn, SetSearchOptions } from "./client/hooks/useSearch.ts";
+export { serializeSearch } from "./client/search-serializer.ts";
 export { useBlocker } from "./client/hooks/useBlocker.ts";
 export { useLocale } from "./client/hooks/useLocale.ts";
 export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
@@ -127,6 +154,8 @@ export type {
   RegisteredRoutes,
   ParamsFor,
   SearchFor,
+  SearchOutputFor,
+  InferSchemaOutput,
   RouteSearchParamsMap,
   RouteContextMap,
 } from "./client/registry.ts";
@@ -141,4 +170,7 @@ export { createDevServer } from "./dev/server.ts";
 export type { DevServerOptions, DevServer } from "./dev/server.ts";
 export { runBuild } from "./build/bundler.ts";
 export type { BuildConfig } from "./build/bundler.ts";
-export { loadUserConfig } from "./config/load.ts";
+export { loadUserConfig, defineConfig } from "./config/load.ts";
+export { runPrerender } from "./build/prerender.ts";
+export type { PrerenderOptions, PrerenderResult } from "./build/prerender.ts";
+export { renderSpaShell } from "./server/spa.ts";

package/src/server/action-handler.ts

@@ -1,29 +1,19 @@
 import { resolveAction } from "./action-registry.ts";
 import { json } from "./response.ts";
-import { isAllowedMutation } from "./csrf.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
 
-// Deep scan: nested objects can carry __proto__ pollution vectors too.
-function hasForbiddenKey(value: unknown, depth = 0): boolean {
-  if (depth > 20 || !value || typeof value !== "object") return false;
-  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"
   // would otherwise also reach this handler).
   if (url.pathname !== "/_action") return null;
   if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
-  if (!isAllowedMutation(request)) return new Response("Forbidden", { status: 403 });
+  if (!isAllowedMutation(request)) return csrfForbiddenResponse();
 
   const id = url.searchParams.get("id");
   if (!id) return new Response("Bad Request: missing action id", { status: 400 });

package/src/server/action-registry.ts

@@ -6,6 +6,37 @@ import { join, relative, resolve, isAbsolute } from "node:path";
 const SERVER_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
 const registry = new Map<string, (...args: unknown[]) => Promise<unknown>>();
 
+// SECURITY(high): exporting a function from a `"use server"` module publishes
+// it as an unauthenticated RPC endpoint reachable via POST /_action and
+// GET /_stream. For files under `routes/`, these reserved exports are framework
+// lifecycle hooks / components — NOT intended as callable actions — so we never
+// register them. Without this filter a route's `loader`/`action`/`default`
+// could be invoked directly over the wire, bypassing search/param validation
+// and (for /_stream) with zero arguments. Authors who genuinely want an action
+// must export it under a different name.
+const RESERVED_ROUTE_EXPORTS = new Set([
+  "default",
+  "loader",
+  "action",
+  "meta",
+  "beforeLoad",
+  "context",
+  "ErrorBoundary",
+  "Fallback",
+  "config",
+  "searchSchema",
+  "ssr",
+]);
+
+function isRouteFile(rel: string): boolean {
+  return rel.startsWith("routes/") || rel.startsWith("routes\\");
+}
+
+function shouldRegisterExport(name: string, fromRouteFile: boolean): boolean {
+  if (fromRouteFile && RESERVED_ROUTE_EXPORTS.has(name)) return false;
+  return true;
+}
+
 /**
  * Hash key for an action — must use the same string the client-side proxy
  * plugin hashes (`pathKey + "#" + name`). Mismatch → `/_action?id=...` 404.
@@ -61,8 +92,10 @@ export async function loadServerActions(appDir: string): Promise<void> {
       continue;
     }
 
+    const fromRouteFile = isRouteFile(rel);
     for (const [name, val] of Object.entries(mod)) {
       if (typeof val !== "function") continue;
+      if (!shouldRegisterExport(name, fromRouteFile)) continue;
       const id = await computeId(pathKeyForAction(filePath, appDir), name);
       registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
     }
@@ -82,8 +115,10 @@ export async function loadServerActionsFromRegistry(
   entries: Array<{ relPath: string; mod: Record<string, unknown> }>,
 ): Promise<void> {
   for (const { relPath, mod } of entries) {
+    const fromRouteFile = isRouteFile(relPath);
     for (const [name, val] of Object.entries(mod)) {
       if (typeof val !== "function") continue;
+      if (!shouldRegisterExport(name, fromRouteFile)) continue;
       const id = await computeId(relPath, name);
       registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
     }

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

package/src/server/api-route.ts

@@ -1,4 +1,6 @@
 import { isExplicitDev } from "./env.ts";
+import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.ts";
+import { hasForbiddenKey } from "./proto-guard.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -8,6 +10,27 @@ export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 // cannot exhaust memory. Same 1 MiB ceiling used by /_action JSON.
 const MAX_BODY_BYTES = 1_048_576;
 
+// SECURITY(high): the same state-changing methods the route-action / _action
+// paths CSRF-gate. A typed API route using one of these is cross-site
+// forgeable (cookies ride along; a form-encoded body is CORS-"simple" and
+// skips preflight) unless the caller proves same-origin. We require that proof
+// by default — see the gate in handleApiRequest.
+const MUTATING_METHODS = new Set<HttpMethod>(["POST", "PUT", "PATCH", "DELETE"]);
+
+export interface ApiRouteOptions {
+  /**
+   * Cross-site-request-forgery protection for this route. Default `true` for
+   * mutating methods (POST/PUT/PATCH/DELETE): the request must be same-origin
+   * (proven via `Sec-Fetch-Site`, the `X-BractJS-Action` header, or a matching
+   * `Origin`), exactly like server actions. Set `false` ONLY for endpoints
+   * that are safe to call cross-site — i.e. they do NOT rely on ambient
+   * credentials (session cookies / Basic auth) and are intentionally public
+   * (webhooks, token-authenticated APIs, public read/write services).
+   * Only GET is exempt from the gate; DELETE is treated as mutating.
+   */
+  csrf?: boolean;
+}
+
 export interface ApiRouteDefinition<
   TMethod extends HttpMethod,
   TPath extends string,
@@ -17,6 +40,8 @@ export interface ApiRouteDefinition<
   method: TMethod;
   path: TPath;
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>;
+  /** Resolved CSRF setting (defaults applied at registration). */
+  csrf: boolean;
   _types: { input: TInput; output: TOutput };
 }
 
@@ -29,6 +54,11 @@ const routeRegistry: ApiRouteDefinition<HttpMethod, string, any, any>[] = [];
  *
  * Usage in app/api/users.ts:
  *   export const getUsers = bract.route("GET", "/api/users", async () => db.users.findAll());
+ *
+ * Mutating routes (POST/PUT/PATCH/DELETE) are CSRF-protected by default — the
+ * request must be same-origin. Pass `{ csrf: false }` for a deliberately public,
+ * credential-free endpoint (e.g. a webhook):
+ *   bract.route("POST", "/api/webhook", handler, { csrf: false });
  */
 export function route<
   TMethod extends HttpMethod,
@@ -39,11 +69,14 @@ export function route<
   method: TMethod,
   path: TPath,
   handler: (input: TInput, request: Request) => TOutput | Promise<TOutput>,
+  options?: ApiRouteOptions,
 ): ApiRouteDefinition<TMethod, TPath, TInput, TOutput> {
   const def: ApiRouteDefinition<TMethod, TPath, TInput, TOutput> = {
     method,
     path,
     handler,
+    // Default ON. Opt out only for endpoints that don't trust ambient creds.
+    csrf: options?.csrf ?? true,
     _types: {} as { input: TInput; output: TOutput },
   };
   routeRegistry.push(def);
@@ -62,6 +95,14 @@ export async function handleApiRequest(request: Request): Promise<Response | nul
     if (def.method !== request.method) continue;
     if (!pathMatches(def.path, url.pathname)) continue;
 
+    // SECURITY(high): CSRF gate for mutating methods. Same check the route
+    // action / _action / _stream paths use, so an authenticated user's cookies
+    // can't be used to forge a cross-site write to an /api route. Routes that
+    // opt out (`csrf: false`) are responsible for not trusting ambient creds.
+    if (def.csrf && MUTATING_METHODS.has(def.method) && !isAllowedMutation(request)) {
+      return csrfForbiddenResponse();
+    }
+
     let input: unknown = undefined;
     if (request.method !== "GET" && request.method !== "DELETE") {
       // Trust an advertised Content-Length up front so oversized payloads
@@ -86,6 +127,12 @@ export async function handleApiRequest(request: Request): Promise<Response | nul
         } catch {
           return new Response("Bad Request: invalid JSON", { status: 400 });
         }
+        // SECURITY(high): reject prototype-pollution keys before the parsed
+        // body reaches a handler that might merge it into another object.
+        // Parity with the /_action JSON path.
+        if (hasForbiddenKey(input)) {
+          return new Response("Bad Request: forbidden keys", { status: 400 });
+        }
       } else if (ct.includes("application/x-www-form-urlencoded") || ct.includes("multipart/form-data")) {
         input = await request.formData();
       }

package/src/server/csp.ts

@@ -21,6 +21,15 @@ export interface CspOptions {
    * Useful for staging a policy before turning it on. Default: false.
    */
   reportOnly?: boolean;
+  /**
+   * Drop `'unsafe-inline'` from the default `style-src`. The baseline policy
+   * allows inline styles for ergonomics (React inline styles, CSS-in-JS), which
+   * leaves inline-style injection (CSS exfiltration / UI redress) possible.
+   * Set `strict: true` for `style-src 'self'` only — you must then serve all
+   * styles from same-origin stylesheets (or override `style-src` yourself with
+   * a nonce/hash via `directives`). Default: false.
+   */
+  strict?: boolean;
 }
 
 /**
@@ -66,14 +75,20 @@ export function csp(options: CspOptions = {}): MiddlewareFn {
 
     const directives: Record<string, string | null> = {
       "default-src": "'self'",
-      // 'strict-dynamic' lets the nonced bootstrap script load the chunks it
-      // imports without each chunk needing its own nonce. Falls back to 'self'
-      // in browsers that don't support it.
+      // 'strict-dynamic': trust flows through the nonce — a nonced script may
+      // load the chunks it imports without each chunk carrying its own nonce.
+      // NOTE: in browsers that support 'strict-dynamic', the 'self' and any
+      // host/allowlist expressions in script-src are IGNORED; only the nonce
+      // (and scripts it transitively loads) are trusted. 'self' is kept solely
+      // as a fallback for older browsers that don't implement 'strict-dynamic'.
       "script-src": `'self' 'nonce-${nonce}' 'strict-dynamic'`,
-      "style-src": "'self' 'unsafe-inline'",
+      "style-src": options.strict ? "'self'" : "'self' 'unsafe-inline'",
       "img-src": "'self' data: blob:",
       "connect-src": "'self'",
       "base-uri": "'self'",
+      // Restrict where <form> can submit so an injected form can't exfiltrate
+      // to an attacker origin even if it slips past other controls.
+      "form-action": "'self'",
       "frame-ancestors": "'self'",
       "object-src": "'none'",
       ...(options.directives ?? {}),

package/src/server/csrf.ts

@@ -23,12 +23,45 @@
  * none of these headers and are rejected by default — they must set
  * `X-BractJS-Action` or a same-origin `Origin` to mutate.
  */
+// This gate protects server actions (/_action), streaming actions (/_stream),
+// route mutations, AND typed /api routes (see api-route.ts) — every
+// state-changing, cookie-trusting surface in the framework.
+//
 // SECURITY(medium): X-BractJS-Action acts as a CSRF token by relying on CORS
 // preflight blocking custom headers cross-origin. This is safe only while the
 // server does NOT emit a permissive Access-Control-Allow-Headers listing this
-// header. If CORS policy is ever loosened, Sec-Fetch-Site (1) remains as the
-// browser-enforced backstop, and apps that loosen CORS should add a
-// cryptographic double-submit token.
+// header. The built-in cors() (middleware/cors.ts) deliberately omits it; if
+// you ship your OWN CORS layer and expose this header cross-origin, you defeat
+// CSRF everywhere — add a cryptographic double-submit token in that case.
+// Sec-Fetch-Site (1) remains a browser-enforced backstop, but note it is NOT
+// sent by every client/proxy: behind a header-stripping proxy the gate falls
+// back to the same-origin Origin check, which cors() does not weaken.
+import { isExplicitDev } from "./env.ts";
+
+/**
+ * The developer-facing explanation of a CSRF rejection. In dev it spells out
+ * the accepted signals and the usual fix; in prod it stays terse so the 403
+ * leaks nothing. Used for the plain route/action 403 bodies — the stream
+ * handler embeds {@link csrfHint} in its SSE error event instead.
+ */
+export function csrfHint(): string {
+  return (
+    "Blocked a cross-site or unattributed mutation (CSRF protection). " +
+    "Same-origin browser requests are allowed automatically; a manual fetch() " +
+    'must send the header `X-BractJS-Action: 1` (BractJS\'s <Form> and ' +
+    "useFetcher do this for you)."
+  );
+}
+
+/** A 403 Response for a rejected mutation: explanatory in dev, terse in prod. */
+export function csrfForbiddenResponse(): Response {
+  if (isExplicitDev()) {
+    console.warn("[bractjs] 403 (CSRF): " + csrfHint());
+    return new Response("Forbidden — " + csrfHint(), { status: 403 });
+  }
+  return new Response("Forbidden", { status: 403 });
+}
+
 export function isAllowedMutation(request: Request): boolean {
   // (1) Browser-enforced signal. If present, it vetoes cross-origin requests
   // regardless of what the Origin/custom headers claim.

package/src/server/env.ts

@@ -20,6 +20,19 @@ export function isDevRuntime(): boolean {
   return _runtimeMode === "dev";
 }
 
+/**
+ * The dev HMR WebSocket port, set by createDevServer and read when rendering
+ * the dev bootstrap so the injected HMR client connects to the right port
+ * (the config's `hmrPort`, not a hardcoded 3001). 0 = default.
+ */
+let _devHmrPort = 0;
+export function setDevHmrPort(port: number): void {
+  _devHmrPort = port;
+}
+export function getDevHmrPort(): number {
+  return _devHmrPort;
+}
+
 /**
  * Strict "is development?" check used to gate sensitive output (error
  * messages, stack traces) that would otherwise leak in production.
@@ -50,12 +63,20 @@ const LS = String.fromCharCode(0x2028);
 const PS = String.fromCharCode(0x2029);
 
 export function safeStringify(data: unknown): string {
-  const seen = new WeakSet();
-  const json = JSON.stringify(data, (_key, value) => {
-    if (typeof value === "object" && value !== null) {
-      if (seen.has(value)) return "[Circular]";
-      seen.add(value);
+  // Cycle detection must track ANCESTORS, not every visited node — a WeakSet
+  // of all seen objects flags legitimate shared references as "[Circular]"
+  // (e.g. a loader echoing `args.search` while the payload also carries
+  // `search` at the top level). MDN's replacer pattern: `this` is the holder
+  // object, so popping the stack until the top is the holder leaves exactly
+  // the current ancestor chain.
+  const ancestors: object[] = [];
+  const json = JSON.stringify(data, function (_key, value: unknown) {
+    if (typeof value !== "object" || value === null) return value;
+    while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) {
+      ancestors.pop();
     }
+    if (ancestors.includes(value)) return "[Circular]";
+    ancestors.push(value);
     return value;
   });
   // Escape HTML-sensitive chars + JS LineTerminators (U+2028 / U+2029) so this

package/src/server/headers.ts

@@ -0,0 +1,49 @@
+import type { LayoutChain } from "./layout.ts";
+import type { LoaderResults } from "./loader.ts";
+import type { HeadersFunction } from "../shared/route-types.ts";
+
+type Params = Record<string, string>;
+
+/**
+ * Walk the route module chain (root → layouts → route) calling each module's
+ * optional `headers()` export, threading the accumulated `Headers` through as
+ * `parentHeaders`. Each call's returned `HeadersInit` is merged on top, so the
+ * innermost route wins per key (RR7 semantics).
+ *
+ * Returns `null` when no module in the chain exports `headers` — callers keep
+ * their existing default headers untouched in that case.
+ */
+export function resolveHeaders(
+  chain: LayoutChain,
+  loaderData: LoaderResults,
+  params: Params,
+  request: Request,
+): Headers | null {
+  const links: Array<{ fn: HeadersFunction; data: unknown }> = [];
+
+  if (chain.root.headers) links.push({ fn: chain.root.headers, data: loaderData.root });
+  chain.layouts.forEach((mod, i) => {
+    if (mod.headers) links.push({ fn: mod.headers, data: loaderData.layouts[i] ?? null });
+  });
+  if (chain.route.headers) links.push({ fn: chain.route.headers, data: loaderData.route });
+
+  if (links.length === 0) return null;
+
+  const merged = new Headers();
+  for (const { fn, data } of links) {
+    const produced = new Headers(fn({ loaderData: data, params, request, parentHeaders: merged }));
+    // `set` (not `append`) so an inner route overrides an ancestor's value for
+    // the same key rather than accumulating duplicates.
+    produced.forEach((value, key) => merged.set(key, value));
+  }
+  return merged;
+}
+
+/**
+ * Copy resolved route headers onto a base headers object, overriding any
+ * same-key defaults. Mutates and returns `base`. No-op when `resolved` is null.
+ */
+export function applyRouteHeaders(base: Headers, resolved: Headers | null): Headers {
+  if (resolved) resolved.forEach((value, key) => base.set(key, value));
+  return base;
+}

package/src/server/layout.ts

@@ -1,5 +1,5 @@
 import { join, resolve } from "node:path";
-import type { RouteFile } from "./scanner.ts";
+import { layoutDirsFromFilePath, type RouteFile } from "./scanner.ts";
 import type { RouteModule } from "../shared/route-types.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
@@ -8,6 +8,12 @@ export interface LayoutChain {
   root: RouteModule;
   layouts: RouteModule[];
   route: RouteModule;
+  /**
+   * appDir-relative source paths for each module in the chain, for error
+   * messages ("loader error in routes/blog/[id].tsx"). Optional so hand-built
+   * chains in tests don't have to supply it.
+   */
+  files?: { root?: string; layouts: string[]; route?: string };
 }
 
 export interface ResolvedRoute extends RouteFile {
@@ -22,21 +28,6 @@ export interface ResolvedRoute extends RouteFile {
  */
 export type ModuleRegistry = Record<string, RouteModule | Record<string, unknown>>;
 
-// ── Helpers ────────────────────────────────────────────────────────────────
-
-/** Derive the ancestor directory segments from a route's urlPattern. */
-function layoutDirs(urlPattern: string): string[] {
-  if (urlPattern === "") return [];
-  const segments = urlPattern.split("/");
-  // For "blog/[id]" → check "routes/blog/layout.tsx" only (not the leaf)
-  segments.pop();
-  const dirs: string[] = [];
-  for (let i = 1; i <= segments.length; i++) {
-    dirs.push(segments.slice(0, i).join("/"));
-  }
-  return dirs;
-}
-
 // ── resolveLayoutChain ─────────────────────────────────────────────────────
 
 export async function resolveLayoutChain(
@@ -52,8 +43,9 @@ export async function resolveLayoutChain(
     layoutFiles.push(rootPath);
   }
 
-  // Intermediate layout.tsx files, outermost → innermost
-  for (const dir of layoutDirs(routeFile.urlPattern)) {
+  // Intermediate layout.tsx files, outermost → innermost. Derived from the
+  // file path so route-group folders ((marketing)/…) contribute their layout.
+  for (const dir of layoutDirsFromFilePath(routeFile.filePath)) {
     const layoutPath = resolve(join(appDir, "routes", dir, "layout.tsx"));
     if (await Bun.file(layoutPath).exists()) {
       layoutFiles.push(layoutPath);
@@ -78,7 +70,7 @@ export function resolveLayoutChainFromRegistry(
   if (registry["root.tsx"]) layoutFiles.push("root.tsx");
   else if (registry["root.ts"]) layoutFiles.push("root.ts");
 
-  for (const dir of layoutDirs(routeFile.urlPattern)) {
+  for (const dir of layoutDirsFromFilePath(routeFile.filePath)) {
     const tsxKey = `routes/${dir}/layout.tsx`;
     const tsKey = `routes/${dir}/layout.ts`;
     if (registry[tsxKey]) layoutFiles.push(tsxKey);
@@ -96,12 +88,24 @@ export async function importRouteModule(filePath: string): Promise<RouteModule>
     loader: mod.loader,
     action: mod.action,
     meta: mod.meta,
+    headers: mod.headers,
+    // SECURITY(high): like beforeLoad, route middleware can be an auth gate —
+    // project it or every `middleware` export becomes a silent no-op.
+    middleware: mod.middleware,
     // SECURITY(high): beforeLoad is the auth/redirect gate and `context` is the
     // per-route context factory. Both MUST be projected here — dropping them
     // turns every beforeLoad() export into a silent no-op, bypassing auth on
     // full-page GET, POST actions, and the /_data soft-nav endpoint alike.
     beforeLoad: mod.beforeLoad,
     context: mod.context,
+    // searchSchema gates loader input — dropping it silently skips search
+    // validation, so loaders would see raw strings where they expect coerced data.
+    searchSchema: mod.searchSchema,
+    // Selective-SSR surface: dropping `ssr` would silently restore full SSR
+    // (running loaders the route opted out of); dropping `Fallback` would
+    // SSR an empty outlet and guarantee a hydration mismatch.
+    ssr: mod.ssr,
+    Fallback: mod.Fallback,
     handle: mod.handle,
     ErrorBoundary: mod.ErrorBoundary,
     default: mod.default,
@@ -120,10 +124,18 @@ function pickRouteModule(mod: Record<string, unknown> | RouteModule | undefined)
     loader: m.loader as RouteModule["loader"],
     action: m.action as RouteModule["action"],
     meta: m.meta as RouteModule["meta"],
+    headers: m.headers as RouteModule["headers"],
+    // SECURITY(high): keep middleware (auth gate) — see importRouteModule.
+    middleware: m.middleware as RouteModule["middleware"],
     // SECURITY(high): keep beforeLoad + context in the projection — see the
     // note in importRouteModule. The compiled-binary path goes through here.
     beforeLoad: m.beforeLoad as RouteModule["beforeLoad"],
     context: m.context as unknown,
+    // Keep searchSchema too — see importRouteModule. Missing it here would
+    // skip search validation only in compiled binaries, the worst kind of skew.
+    searchSchema: m.searchSchema,
+    ssr: m.ssr as RouteModule["ssr"],
+    Fallback: m.Fallback as RouteModule["Fallback"],
     handle: m.handle as RouteModule["handle"],
     ErrorBoundary: m.ErrorBoundary as RouteModule["ErrorBoundary"],
     default: m.default as RouteModule["default"],
@@ -155,7 +167,12 @@ export async function resolveRouteChain(
     const layoutMods = layoutKeys.map((k) => pickRouteModule(registry[k]));
     const routeKey = routeFile.filePath.split("\\").join("/");
     const routeMod = pickRouteModule(registry[routeKey]);
-    return { root: rootMod, layouts: layoutMods, route: routeMod };
+    return {
+      root: rootMod,
+      layouts: layoutMods,
+      route: routeMod,
+      files: { root: rootKey, layouts: layoutKeys, route: routeKey },
+    };
   }
 
   const resolved = await resolveLayoutChain(routeFile, appDir);
@@ -167,9 +184,15 @@ export async function resolveRouteChain(
     resolve(join(appDir, routeFile.filePath))
   );
 
+  // Relativize the absolute layout paths back to appDir-relative for messages.
+  const appRoot = resolve(appDir);
+  const rel = (abs: string) => abs.startsWith(appRoot + "/") ? abs.slice(appRoot.length + 1) : abs;
+  const [rootFile, ...layoutFiles] = resolved.layoutFiles.map(rel);
+
   return {
     root: rootMod ?? {},
     layouts: layoutMods,
     route: routeMod,
+    files: { root: rootFile, layouts: layoutFiles, route: routeFile.filePath },
   };
 }