@bractjs/bractjs 0.1.28 → 0.2.0

package/src/codegen/module-registry.ts

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

package/src/codegen/route-codegen.ts

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

package/src/config/load.ts

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

package/src/index.ts

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

package/src/server/action-handler.ts

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

package/src/server/adapter.ts

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

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;
+}