@bractjs/bractjs 0.1.28 → 0.1.29

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

@@ -75,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": 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,19 @@
  * 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";
 
 /**

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 ──────────────────────────────────────────────────────────────────
@@ -28,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(
@@ -58,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);
@@ -84,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);
@@ -102,6 +88,10 @@ 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
@@ -134,6 +124,9 @@ 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"],

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,6 +1,6 @@
 import { renderToReadableStream } from "react-dom/server";
 import { createElement, Fragment, type ReactNode } from "react";
-import type { MetaDescriptor } from "../shared/route-types.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";
@@ -22,6 +22,8 @@ export interface RenderOptions {
   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;
@@ -34,6 +36,11 @@ export interface RenderOptions {
    * "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> {
@@ -59,7 +66,7 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
   // 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, search: options.search, manifest, routeFile: options.routeFile, meta: mergedMeta, ssrMode: options.ssrMode })};`;
+    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
@@ -90,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 });
 }