@bractjs/bractjs 0.1.27 → 0.1.29

package/src/server/scanner.ts

@@ -2,7 +2,11 @@ import { basename } from "node:path";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
-export type Segment = string | { param: string } | { catchAll: string };
+export type Segment =
+  | string
+  | { param: string }
+  | { optional: string }
+  | { catchAll: string };
 
 export interface RouteFile {
   filePath: string;
@@ -12,12 +16,22 @@ export interface RouteFile {
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
+/** A path segment that is a route group: `(marketing)`. Contributes a layout
+ *  folder but no URL segment. */
+export function isRouteGroupSegment(seg: string): boolean {
+  return seg.startsWith("(") && seg.endsWith(")") && seg.length > 2;
+}
+
 export function pathToSegments(pattern: string): Segment[] {
   if (pattern === "") return [];
   return pattern.split("/").map((seg) => {
     if (seg.startsWith("[...") && seg.endsWith("]")) {
       return { catchAll: seg.slice(4, -1) };
     }
+    // Optional param: [[id]] → matches with or without the segment present.
+    if (seg.startsWith("[[") && seg.endsWith("]]")) {
+      return { optional: seg.slice(2, -2) };
+    }
     if (seg.startsWith("[") && seg.endsWith("]")) {
       return { param: seg.slice(1, -1) };
     }
@@ -29,20 +43,48 @@ export function filePathToPattern(filePath: string): string {
   // Strip "routes/" prefix and file extension
   let path = filePath.replace(/^routes\//, "").replace(/\.(tsx|ts)$/, "");
 
+  // Drop route-group segments — `(marketing)/about` → `about`. They group
+  // files (and their layout.tsx) without adding a URL segment.
+  path = path
+    .split("/")
+    .filter((seg) => !isRouteGroupSegment(seg))
+    .join("/");
+
   // Handle nested _index (e.g. blog/_index → blog)
   path = path.replace(/\/_index$/, "");
 
   // Handle root _index
   if (path === "_index" || path === "") return "";
 
-  // Convert [param] and [...catchAll] segments — keep as-is for pattern string
+  // Convert [param], [[optional]], and [...catchAll] segments — keep as-is for
+  // the pattern string.
   return path;
 }
 
+/**
+ * Ancestor directory chain (relative to `routes/`) for a route file, outermost
+ * → innermost, used to locate nesting `layout.tsx` files. Derived from the FILE
+ * path (not the URL pattern) so route-group folders like `(marketing)` are
+ * included — their layout wraps children even though they add no URL segment.
+ *
+ * `routes/(marketing)/blog/[id].tsx` → `["(marketing)", "(marketing)/blog"]`.
+ */
+export function layoutDirsFromFilePath(filePath: string): string[] {
+  const rel = filePath.replace(/^routes\//, "").replace(/\.(tsx|ts)$/, "");
+  const parts = rel.split("/");
+  parts.pop(); // drop the file's own basename — only ancestor dirs hold layouts
+  const dirs: string[] = [];
+  for (let i = 1; i <= parts.length; i++) {
+    dirs.push(parts.slice(0, i).join("/"));
+  }
+  return dirs;
+}
+
 function segmentScore(seg: Segment): number {
   if (typeof seg === "string") return 0;       // static
   if ("param" in seg) return 1;                // dynamic
-  return 2;                                    // catch-all
+  if ("optional" in seg) return 2;             // optional dynamic
+  return 3;                                    // catch-all
 }
 
 function routeScore(route: RouteFile): number {

package/src/server/search.ts

@@ -0,0 +1,47 @@
+import { runSchema, type Schema } from "./validate.ts";
+
+// ── Raw extraction ─────────────────────────────────────────────────────────
+
+/**
+ * URLSearchParams → plain object. Repeated keys collapse into arrays
+ * (`?tag=a&tag=b` → `{ tag: ["a", "b"] }`), mirroring how `validate()`
+ * flattens FormData.
+ */
+export function searchParamsToObject(sp: URLSearchParams): Record<string, string | string[]> {
+  // Null-prototype so a query param named "__proto__" (?__proto__=x) can't
+  // pollute Object.prototype when the result is later spread/merged. Using a
+  // plain {} here would make `out["__proto__"] = …` a no-op AND, for nested
+  // merges downstream, a pollution vector. SECURITY: see proto-guard.ts.
+  const out = Object.create(null) as Record<string, string | string[]>;
+  for (const [key, value] of sp.entries()) {
+    const existing = out[key];
+    if (existing === undefined) out[key] = value;
+    else if (Array.isArray(existing)) existing.push(value);
+    else out[key] = [existing, value];
+  }
+  return out;
+}
+
+// ── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate a URL's search params against a route's optional `searchSchema`
+ * export (Zod/Valibot/standard-schema compatible — same duck typing as
+ * `validate()`).
+ *
+ * - No schema → the raw string record (back-compat: routes that never opted in
+ *   see exactly what `request.url` would give them).
+ * - Schema failure → throws the 400 `Response` from the validate machinery.
+ *   Loaders must never run on unvalidated input; leniency belongs in the
+ *   schema itself (`z.coerce.number().catch(1)` is the documented idiom for
+ *   URLs that must tolerate junk).
+ * - Success → the parsed, coerced object (numbers/booleans/arrays/defaults).
+ */
+export async function validateSearch(
+  schema: unknown,
+  url: URL,
+): Promise<Record<string, unknown>> {
+  const raw = searchParamsToObject(url.searchParams);
+  if (!schema) return raw;
+  return await runSchema(schema as Schema<Record<string, unknown>>, raw);
+}

package/src/server/serve.ts

@@ -1,6 +1,8 @@
 import { scanRoutes, type RouteFile } from "./scanner.ts";
-import { buildTrie } from "./matcher.ts";
+import { buildTrie, matchRoute } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
+import { pipeline, type MiddlewareContext } from "./middleware.ts";
+import { renderSpaShell } from "./spa.ts";
 import { type ServerManifest } from "./render.ts";
 import { isDevRuntime, isExplicitDev } from "./env.ts";
 import { loadManifest } from "../build/manifest.ts";
@@ -24,10 +26,24 @@ export interface BractJSConfig {
   appDir: string;
   publicDir: string;
   manifest: ServerManifest;
+  /** WebSocket port for dev HMR (used by `bractjs dev` only). Default 3001. */
+  hmrPort?: number;
   /** Optional custom adapter (Cloudflare Workers, Deno, Node, etc.). Defaults to Bun.serve(). */
   adapter?: BractAdapter;
   /** i18n locale prefix routing (E2). */
   i18n?: I18nConfig;
+  /**
+   * SPA mode: `false` serves one static shell for every document GET instead
+   * of SSR. The server keeps running — /_data, actions, /_image, API routes
+   * and static assets behave exactly as in SSR mode ("no document SSR", not
+   * "no server"). Default `true`.
+   */
+  ssr?: boolean;
+  /**
+   * Paths to prerender at build time (SSG). Served from disk before dynamic
+   * SSR in production; requests with a query string stay dynamic.
+   */
+  prerender?: string[] | (() => string[] | Promise<string[]>);
   // Build options (used by src/build/bundler.ts)
   sourcemap?: "none" | "linked" | "inline" | "external";
   minify?: boolean;
@@ -37,6 +53,14 @@ export interface BractJSConfig {
   buildDir?: string;
   /** Directory for transformed image cache. Defaults to .bract-image-cache */
   imageCacheDir?: string;
+  /**
+   * Hard ceiling (bytes) on the size of any incoming request body, enforced by
+   * the Bun adapter regardless of the advertised Content-Length. Defaults to
+   * 16 MiB — above the 10 MiB route-form cap so normal requests pass while a
+   * single client can't stream an unbounded body into memory. Raise it for a
+   * dedicated large-upload endpoint. Only applies to the default Bun adapter.
+   */
+  maxRequestBodySize?: number;
   /** Called once after the server starts listening. Use to open DB connections, warm caches, etc. */
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
@@ -129,8 +153,38 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     : loadServerActions(appDir);
   const moduleRegistry = config.moduleRegistry;
   const onError = config.onError;
+  const ssrEnabled = config.ssr !== false;
+
+  // SPA shell: production prefers the file `bractjs build` wrote; dev (or a
+  // missing file) renders it on demand so root.tsx edits show up. Cached per
+  // manifest in prod-without-file; never cached in dev.
+  let spaShellCache: { key: string; html: string } | null = null;
+  async function getSpaShell(manifest: ServerManifest): Promise<string> {
+    if (!isDevRuntime()) {
+      const file = Bun.file(join(buildDir, "client", "__spa.html"));
+      if (await file.exists()) return file.text();
+      const key = manifest.clientEntry;
+      if (spaShellCache?.key === key) return spaShellCache.html;
+      const html = await renderSpaShell(appDir, manifest, moduleRegistry);
+      spaShellCache = { key, html };
+      return html;
+    }
+    return renderSpaShell(appDir, manifest, moduleRegistry);
+  }
 
-  return async function fetch(request: Request): Promise<Response> {
+  /** Prerendered file for a clean (query-free, dot-free) document path, or null. */
+  function prerenderFile(relHtmlOrJson: string): ReturnType<typeof Bun.file> | null {
+    if (relHtmlOrJson.split("/").some((s) => s === ".." || s === ".")) return null;
+    return Bun.file(join(buildDir, "client", "_prerender", relHtmlOrJson));
+  }
+
+  // The full per-request dispatch: special endpoints (API, actions, stream,
+  // image, static, prerender) first, then the SSR route handler. Runs INSIDE
+  // the global middleware pipeline (see the returned `fetch` below), so
+  // `pipeline.use(cors()/csp()/auth/…)` governs every response — not just SSR
+  // documents. `context` is the shared mutable object threaded through the
+  // pipeline; route-level middleware and getCspNonce() read the same object.
+  async function dispatch(request: Request, context: Record<string, unknown>): Promise<Response> {
     const url = new URL(request.url);
     const { pathname } = url;
 
@@ -196,9 +250,67 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
     if (staticRes) return staticRes;
 
     const trie = await trieReady;
+    const isDocGet = request.method === "GET" || request.method === "HEAD";
+
+    // SPA mode: every document GET that matches a route gets the static
+    // shell. /_data (no trie match) and mutations fall through to the normal
+    // handler, so loaders/actions/CSRF behave exactly as in SSR mode.
+    if (!ssrEnabled && isDocGet && matchRoute(pathname, trie)) {
+      const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
+      return new Response(await getSpaShell(manifest), {
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-cache",
+        },
+      });
+    }
+
+    // Prerendered output (production): serve the build-time HTML / _data
+    // payload for clean URLs. A query string opts the request back into
+    // dynamic SSR — the static file was rendered without one.
+    if (!isDevRuntime() && isDocGet) {
+      if (pathname === "/_data") {
+        const target = url.searchParams.get("path") ?? "/";
+        const [targetPathname, targetSearch] = target.split("?");
+        if (!targetSearch) {
+          const rel = targetPathname === "/" ? "_data.json" : targetPathname.slice(1) + "/_data.json";
+          const f = prerenderFile(rel);
+          if (f && (await f.exists())) {
+            return new Response(f, {
+              headers: {
+                "Content-Type": "application/json",
+                "Cache-Control": "public, max-age=0, must-revalidate",
+              },
+            });
+          }
+        }
+      } else if (!url.search) {
+        const rel = pathname === "/" ? "index.html" : pathname.slice(1) + "/index.html";
+        const f = prerenderFile(rel);
+        if (f && (await f.exists())) {
+          return new Response(f, {
+            headers: {
+              "Content-Type": "text/html; charset=utf-8",
+              "Cache-Control": "public, max-age=0, must-revalidate",
+            },
+          });
+        }
+      }
+    }
+
     const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
     const handlerConfig: HandlerConfig = { appDir, publicDir, manifest, onError, moduleRegistry };
-    return handleRequest(request, trie, handlerConfig);
+    return handleRequest(request, trie, handlerConfig, context);
+  }
+
+  return async function fetch(request: Request): Promise<Response> {
+    // Run the global middleware pipeline around the ENTIRE dispatch so
+    // cors()/csp()/logging/auth attached via `pipeline.use(...)` apply to
+    // API routes, server actions, /_stream, /_image and static assets — not
+    // only SSR documents. The per-route (nested) middleware chain still runs
+    // inside handleRequest for SSR/_data, sharing this same `context` object.
+    const ctx: MiddlewareContext = { request, params: {}, context: {} };
+    return pipeline.run(ctx, () => dispatch(request, ctx.context));
   };
 }
 
@@ -243,7 +355,7 @@ export function createServer(config?: Partial<BractJSConfig>): {
   const fetchHandler = buildFetchHandler(config ?? {});
 
   // Use provided adapter or fall back to the default Bun adapter.
-  const adapter = config?.adapter ?? new BunAdapter();
+  const adapter = config?.adapter ?? new BunAdapter(config?.maxRequestBodySize);
 
   if (adapter instanceof BunAdapter) {
     adapter.setHandler(fetchHandler);

package/src/server/session.ts

@@ -1,3 +1,5 @@
+import { hasForbiddenKey } from "./proto-guard.ts";
+
 export type SessionData = Record<string, unknown>;
 
 export interface Session {
@@ -37,7 +39,16 @@ function encode(data: SessionData): string {
 
 function decode(encoded: string): SessionData {
   const pad = "=".repeat((4 - (encoded.length % 4)) % 4);
-  return JSON.parse(atob(encoded.replace(/-/g, "+").replace(/_/g, "/") + pad)) as SessionData;
+  const parsed = JSON.parse(
+    atob(encoded.replace(/-/g, "+").replace(/_/g, "/") + pad),
+  ) as SessionData;
+  // Defense-in-depth: the payload is HMAC-verified before we get here, so this
+  // only matters if a signing secret leaks — but a session blob carrying a
+  // "__proto__" key must never pollute Object.prototype when read/spread.
+  if (hasForbiddenKey(parsed)) {
+    throw new Error("session: forbidden key in payload");
+  }
+  return parsed;
 }
 
 async function sign(data: string, secret: string): Promise<string> {

package/src/server/spa.ts

@@ -0,0 +1,62 @@
+import { createElement, type ComponentType } from "react";
+import { join, resolve } from "node:path";
+import { renderRoute, type ServerManifest } from "./render.ts";
+import { BractJSProvider, type RouteManifest } from "../shared/context.ts";
+import type { ModuleRegistry } from "./layout.ts";
+
+/**
+ * Render the SPA-mode document shell: the app's root component around an
+ * empty outlet, with `ssrMode: "spa"` in the bootstrap payload. Served for
+ * every document GET when the config sets `ssr: false`; the client router
+ * resolves the actual route (module + /_data) after hydration.
+ *
+ * The root renders with NO loader data (its loader does not run for the
+ * shell) and a "/" location — roots that render loader- or location-dependent
+ * markup are not compatible with SPA mode. Loaders/actions stay fully
+ * functional at runtime: SPA mode means "no document SSR", not "no server".
+ */
+export async function renderSpaShell(
+  appDir: string,
+  manifest: ServerManifest,
+  registry?: ModuleRegistry,
+): Promise<string> {
+  let RootComponent: ComponentType = () => null;
+  if (registry) {
+    const rootMod = (registry["root.tsx"] ?? registry["root.ts"]) as { default?: ComponentType } | undefined;
+    if (rootMod?.default) RootComponent = rootMod.default;
+  } else {
+    const rootPath = resolve(join(appDir, "root.tsx"));
+    if (await Bun.file(rootPath).exists()) {
+      const mod = (await import(rootPath)) as { default?: ComponentType };
+      if (mod.default) RootComponent = mod.default;
+    }
+  }
+
+  const loaderData = { root: null, layouts: [], route: null };
+  const shell = createElement(BractJSProvider, {
+    value: {
+      loaderData: loaderData as unknown as Record<string, unknown>,
+      actionData: null,
+      params: {},
+      pathname: "/",
+      manifest: manifest as unknown as RouteManifest,
+      RouteComponent: undefined,
+      location: { pathname: "/", search: "", hash: "", state: null, key: "default" },
+      search: {},
+    },
+    children: createElement(RootComponent),
+  });
+
+  const res = await renderRoute({
+    shell,
+    loaderData: loaderData as unknown as Record<string, unknown>,
+    actionData: null,
+    params: {},
+    pathname: "/",
+    search: {},
+    manifest,
+    meta: [],
+    ssrMode: "spa",
+  });
+  return await res.text();
+}

package/src/server/stream-handler.ts

@@ -1,5 +1,6 @@
 import { resolveAction } from "./action-registry.ts";
 import { isExplicitDev } from "./env.ts";
+import { csrfHint } from "./csrf.ts";
 
 // ── SSE helpers ────────────────────────────────────────────────────────────
 
@@ -31,7 +32,7 @@ export async function handleStreamRequest(request: Request): Promise<Response |
   // it cross-origin without a CORS preflight, and the real client (useFetcher)
   // always sends it. This is strictly tighter than the /_action gate.
   if (!request.headers.get("X-BractJS-Action")) {
-    return new Response(sseChunk("error", { message: "Forbidden" }), {
+    return new Response(sseChunk("error", { message: isExplicitDev() ? csrfHint() : "Forbidden" }), {
       status: 403,
       headers: {
         "Content-Type": "text/event-stream",
@@ -70,6 +71,14 @@ export async function handleStreamRequest(request: Request): Promise<Response |
     async start(controller) {
       const encoder = new TextEncoder();
       try {
+        // SECURITY(medium): /_stream invokes the resolved action with NO
+        // caller-supplied arguments (GET carries no body, and we deliberately
+        // pass none). Any function reachable here therefore runs purely on
+        // server-side state. The X-BractJS-Action gate above blocks browser
+        // cross-origin abuse; the action-registry's RESERVED_ROUTE_EXPORTS
+        // filter keeps route lifecycle exports (loader/action/…) from ever
+        // being resolvable. Authors must still ensure stream actions are safe
+        // to call with no input and perform their own authorization.
         const result = await action();
         // If the action is an async generator, stream each value.
         if (result && typeof (result as AsyncIterable<unknown>)[Symbol.asyncIterator] === "function") {

package/src/server/validate.ts

@@ -14,7 +14,7 @@ interface SchemaWithSafeParse<T> {
   safeParse(input: unknown): SafeParseResult<T> | Promise<SafeParseResult<T>>;
 }
 
-type Schema<T> = SchemaWithParse<T> | SchemaWithSafeParse<T>;
+export type Schema<T> = SchemaWithParse<T> | SchemaWithSafeParse<T>;
 
 // ── Field error shape ─────────────────────────────────────────────────────
 
@@ -33,7 +33,10 @@ export class ValidationError extends Error {
 
 function toPlainObject(input: FormData | Record<string, unknown>): Record<string, unknown> {
   if (input instanceof FormData) {
-    const out: Record<string, unknown> = {};
+    // Null-prototype: a form field literally named "__proto__" becomes a plain
+    // own key here instead of mutating Object.prototype when the result is
+    // later spread/merged. SECURITY: see src/server/proto-guard.ts.
+    const out = Object.create(null) as Record<string, unknown>;
     for (const [key, value] of input.entries()) {
       if (key in out) {
         const existing = out[key];
@@ -48,21 +51,15 @@ function toPlainObject(input: FormData | Record<string, unknown>): Record<string
 }
 
 /**
- * Validate `input` against a Zod-compatible or Valibot-compatible schema.
- *
- * - If the schema has `.safeParse()`: uses it to collect field errors and throws
- *   a typed `ValidationError` on failure (which the framework converts to a 400).
- * - If the schema only has `.parse()`: wraps it and re-throws the error as a
- *   `ValidationError` with a single `_` field containing the error message.
- *
- * Returns the parsed (coerced) data on success.
+ * Run a plain object through a Zod/Valibot-compatible schema. The shared core
+ * of `validate()` (action/form bodies) and `validateSearch()` (URL search
+ * params). Throws a 400 `Response` with `{ errors }` field errors on failure;
+ * returns the parsed (coerced) data on success.
  */
-export async function validate<T>(
+export async function runSchema<T>(
   schema: Schema<T>,
-  input: FormData | Record<string, unknown>,
+  plain: Record<string, unknown>,
 ): Promise<T> {
-  const plain = toPlainObject(input);
-
   if ("safeParse" in schema && typeof schema.safeParse === "function") {
     const result = await schema.safeParse(plain);
     if ((result as SafeParseResult<T>).success) {
@@ -87,3 +84,81 @@ export async function validate<T>(
     throw Response.json({ errors: fieldErrors }, { status: 400, statusText: "Validation failed" });
   }
 }
+
+/**
+ * Validate `input` against a Zod-compatible or Valibot-compatible schema.
+ *
+ * - If the schema has `.safeParse()`: uses it to collect field errors and throws
+ *   a typed `ValidationError` on failure (which the framework converts to a 400).
+ * - If the schema only has `.parse()`: wraps it and re-throws the error as a
+ *   `ValidationError` with a single `_` field containing the error message.
+ *
+ * Returns the parsed (coerced) data on success.
+ */
+export async function validate<T>(
+  schema: Schema<T>,
+  input: FormData | Record<string, unknown>,
+): Promise<T> {
+  return runSchema(schema, toPlainObject(input));
+}
+
+// ── Non-throwing validation (ergonomic action idiom) ───────────────────────
+
+export type SafeValidateResult<T> =
+  | { ok: true; data: T }
+  | { ok: false; fieldErrors: FieldErrors; firstError: string };
+
+/**
+ * Like {@link validate}, but returns a result instead of throwing — the
+ * ergonomic shape for actions that want to render field errors:
+ *
+ * ```ts
+ * const r = await safeValidate(PostSchema, formData);
+ * if (!r.ok) return { error: r.firstError, fieldErrors: r.fieldErrors };
+ * usePost(r.data);
+ * ```
+ *
+ * `firstError` is the first message across all fields, or a generic fallback.
+ */
+export async function safeValidate<T>(
+  schema: Schema<T>,
+  input: FormData | Record<string, unknown>,
+): Promise<SafeValidateResult<T>> {
+  try {
+    const data = await runSchema(schema, toPlainObject(input));
+    return { ok: true, data };
+  } catch (err) {
+    if (isValidationResponse(err)) {
+      const { fieldErrors, firstError } = await readValidationError(err);
+      return { ok: false, fieldErrors, firstError };
+    }
+    throw err; // not a validation failure — let it propagate
+  }
+}
+
+/**
+ * True for the 400 `Response` thrown by {@link validate} / `searchSchema`
+ * validation (identified by status 400 + `statusText "Validation failed"`).
+ * Use it in the try/catch idiom when you keep calling `validate()` directly.
+ */
+export function isValidationResponse(value: unknown): value is Response {
+  return value instanceof Response && value.status === 400 && value.statusText === "Validation failed";
+}
+
+/**
+ * Parse the `{ errors }` body of a validation 400 `Response` into field errors
+ * plus the first message. Tolerant of a non-JSON / unexpected body.
+ */
+export async function readValidationError(
+  res: Response,
+): Promise<{ fieldErrors: FieldErrors; firstError: string }> {
+  const fallback = "Please check your input.";
+  try {
+    const body = (await res.clone().json()) as { errors?: FieldErrors };
+    const fieldErrors = body.errors ?? {};
+    const firstError = Object.values(fieldErrors)[0]?.[0] ?? fallback;
+    return { fieldErrors, firstError };
+  } catch {
+    return { fieldErrors: {}, firstError: fallback };
+  }
+}

package/src/shared/context.ts

@@ -1,4 +1,5 @@
 import { createContext, useContext, createElement, type ComponentType, type ReactNode } from "react";
+import type { RouterLocation, RouteMatch } from "./route-types.ts";
 
 export interface RouteManifest {
   [routeId: string]: {
@@ -15,6 +16,12 @@ export interface BractJSContextValue {
   manifest: RouteManifest;
   /** SSR-only: the matched route's default export so <Outlet> can render it without ClientRouter */
   RouteComponent?: ComponentType;
+  /** The request's location, so `useLocation()` works during SSR (hash is always ""). */
+  location?: RouterLocation;
+  /** Validated search params (route `searchSchema` output), so `useSearch()` works during SSR. */
+  search?: Record<string, unknown>;
+  /** The matched route chain (root → layouts → route) for `useMatches()`. */
+  matches?: RouteMatch[];
 }
 
 export const BractJSContext = createContext<BractJSContextValue>(null!);

package/src/shared/define-actions.ts

@@ -0,0 +1,39 @@
+import type { ActionArgs } from "./route-types.ts";
+import { isExplicitDev } from "../server/env.ts";
+
+type IntentHandler = (args: ActionArgs) => unknown;
+
+/**
+ * Compose a single route `action` from per-intent handlers, dispatching on the
+ * form's `intent` field. Pairs with `<Form intent="...">` / `<fetcher.Form
+ * intent="...">`, which render the matching hidden input:
+ *
+ * ```ts
+ * export const action = defineActions({
+ *   add:    ({ formData }) => addTodo(formText(formData, "title")),
+ *   delete: ({ formData }) => deleteTodo(formText(formData, "id")),
+ * });
+ * ```
+ *
+ * A missing or unknown intent returns a 400 `Response` (dev lists the known
+ * intents; prod is terse). Each handler receives the full {@link ActionArgs}.
+ */
+export function defineActions<M extends Record<string, IntentHandler>>(
+  handlers: M,
+): (args: ActionArgs) => Promise<Awaited<ReturnType<M[keyof M]>> | Response> {
+  type Out = Awaited<ReturnType<M[keyof M]>> | Response;
+  const dispatch = async (args: ActionArgs): Promise<Out> => {
+    const raw = args.formData.get("intent");
+    const intent = typeof raw === "string" ? raw : "";
+    const handler = handlers[intent];
+    if (!handler) {
+      const known = Object.keys(handlers);
+      const message = isExplicitDev()
+        ? `Unknown action intent ${JSON.stringify(intent)}. Known intents: ${known.join(", ") || "(none)"}.`
+        : "Unknown action intent.";
+      return Response.json({ error: message }, { status: 400 });
+    }
+    return (await handler(args)) as Out;
+  };
+  return dispatch;
+}

package/src/shared/form-data.ts

@@ -0,0 +1,34 @@
+// Small ergonomics for reading FormData in actions, where `.get()` returns
+// `string | File | null` and almost every call site coerces to a string.
+
+/**
+ * Read a string field from FormData. Returns `""` when the field is missing or
+ * is a File (upload) — never `null`/`File`, so it drops straight into code that
+ * expects a string. Replaces the `String(formData.get("x") ?? "")` dance.
+ */
+export function formText(formData: FormData, key: string): string {
+  const value = formData.get(key);
+  return typeof value === "string" ? value : "";
+}
+
+/**
+ * Collect string fields from FormData into a plain object. With no `keys`, every
+ * string entry is included (Files are skipped, first occurrence wins per key);
+ * with `keys`, only those fields (each defaulting to `""`). Handy for passing a
+ * typed subset of a form to a model function.
+ */
+export function formValues(
+  formData: FormData,
+  keys?: string[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (keys) {
+    for (const key of keys) out[key] = formText(formData, key);
+    return out;
+  }
+  for (const [key, value] of formData.entries()) {
+    if (key in out) continue; // first occurrence wins (mirrors FormData.get)
+    if (typeof value === "string") out[key] = value;
+  }
+  return out;
+}