@bractjs/bractjs 0.1.27 → 0.1.28

package/src/codegen/route-codegen.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 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.
 function patternToColon(urlPattern: string): string {
@@ -34,6 +35,8 @@ function substituteParams(pattern: string, params: string[]): string {
 // backtick, ${ }, or quote into the generated TS source.
 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._\/\-\[\]]+$/;
 
 function assertSafePattern(pattern: string): void {
   if (!SAFE_PATTERN_RE.test(pattern)) {
@@ -45,6 +48,11 @@ function assertSafeParam(name: string): void {
     throw new Error(`[bractjs] codegen: refusing to emit unsafe param name: ${JSON.stringify(name)}`);
   }
 }
+function assertSafeFilePath(filePath: string): void {
+  if (!SAFE_FILEPATH_RE.test(filePath) || filePath.split("/").includes("..")) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe file path: ${JSON.stringify(filePath)}`);
+  }
+}
 
 function builderEntry(pattern: string, params: string[]): string {
   assertSafePattern(pattern);
@@ -110,6 +118,38 @@ function searchParamsTypeLines(routes: Array<{ pattern: string }>): string {
   ].join("\n");
 }
 
+// Per-route VALIDATED search shapes, inferred from each route's `searchSchema`
+// export via type-only `typeof import(...)`. Routes without a schema fall back
+// to the user's RouteSearchParamsMap augmentation, then a permissive record.
+// This map feeds `Register.routes.searchOutput` → `useSearch`/`useSetSearch`/
+// `<Link search>`; the legacy string-valued `search` member is untouched.
+function searchOutputTypeLines(routes: Array<{ pattern: string; filePath: string }>): string {
+  if (routes.length === 0) {
+    return "export type GeneratedSearchOutput = Record<never, never>;";
+  }
+  const entries = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      assertSafeFilePath(r.filePath);
+      const key = JSON.stringify(r.pattern);
+      const spec = JSON.stringify("./" + r.filePath.split("\\").join("/"));
+      return "  " + key + ": typeof import(" + spec + ") extends { searchSchema: infer S }\n" +
+        "    ? InferSchemaOutput<S>\n" +
+        "    : (RouteSearchParamsMap extends Record<" + key + ", infer V> ? V : Record<string, unknown>);";
+    })
+    .join("\n");
+  return [
+    "// Validated search shape per route, inferred from `searchSchema` exports.",
+    "export type GeneratedSearchOutput = {",
+    entries,
+    "};",
+    "",
+    "/** Validated search object for a route — what `useSearch<T>()` returns. */",
+    "export type SearchOutput<T extends AppRoutes> =",
+    "  T extends keyof GeneratedSearchOutput ? GeneratedSearchOutput[T] : Record<string, unknown>;",
+  ].join("\n");
+}
+
 function contextTypeLines(routes: Array<{ pattern: string }>): string {
   if (routes.length === 0) {
     return "export type Context<_T extends AppRoutes> = Record<string, unknown>;";
@@ -156,18 +196,87 @@ function registerAugmentationLines(routes: Array<{ pattern: string; params: stri
     paramEntries,
     "      };",
     "      search: RouteSearchParamsMap;",
+    "      searchOutput: GeneratedSearchOutput;",
     "    };",
     "  }",
     "}",
   ].join("\n");
 }
 
+// ── Freshness fingerprint ────────────────────────────────────────────────
+// The generated file embeds a hash of its route patterns so the dev server can
+// detect drift precisely (and skip rewrites when nothing changed, which would
+// otherwise trigger an editor reload loop). Patterns are sorted everywhere so
+// the output is identical across machines regardless of filesystem scan order.
+
+const FINGERPRINT_RE = /^\/\/ bractjs:routes ([0-9a-f]+) \((\d+) routes?\)$/m;
+
+/** Stable 8-hex fingerprint of a route-pattern set (order-independent). */
+export function routesFingerprint(patterns: string[]): Promise<string> {
+  return hashString([...patterns].sort().join("\n"));
+}
+
+/** Extract the fingerprint hash previously written into a generated file, or null. */
+export function readFingerprint(src: string | null): string | null {
+  if (!src) return null;
+  const m = src.match(FINGERPRINT_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * A precise human-readable reason the generated types are stale, or null when
+ * fresh. `patterns` must be colon-style (the form the generated file embeds);
+ * prefer {@link explainStalenessForApp} which derives them for you.
+ */
+export async function explainStaleness(
+  oldSrc: string | null,
+  patterns: string[],
+): Promise<string | null> {
+  if (!oldSrc) return "route-types.gen.ts is missing — generating it";
+  const current = await routesFingerprint(patterns);
+  if (readFingerprint(oldSrc) === current) return null;
+  // Recover the old pattern set from the union members to report add/remove
+  // counts. The last member ends with `;`, so allow an optional trailing `;`.
+  const old = new Set(
+    [...oldSrc.matchAll(/^ {2}\| "([^"]+)";?$/gm)].map((m) => m[1]),
+  );
+  const now = new Set(patterns);
+  const added = patterns.filter((p) => !old.has(p)).length;
+  const removed = [...old].filter((p) => !now.has(p)).length;
+  const parts: string[] = [];
+  if (added) parts.push(`+${added} added`);
+  if (removed) parts.push(`-${removed} removed`);
+  const detail = parts.length ? ` (${parts.join(", ")})` : "";
+  return `routes changed since last codegen${detail} — regenerating`;
+}
+
+/** Colon-style route patterns for an app dir (the form the generated file uses). */
+export async function routePatternsForApp(appDir: string): Promise<string[]> {
+  const routeFiles = await scanRoutes(appDir);
+  return routeFiles.map((r) => patternToColon(r.urlPattern));
+}
+
+/** {@link explainStaleness} against the current generated file + route set on disk. */
+export async function explainStalenessForApp(
+  appDir: string,
+  outPath?: string,
+): Promise<string | null> {
+  const dest = outPath ?? join(appDir, "route-types.gen.ts");
+  const existing = await Bun.file(dest).text().catch(() => null);
+  return explainStaleness(existing, await routePatternsForApp(appDir));
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
-  const routes = routeFiles.map((r) => ({
-    pattern: patternToColon(r.urlPattern),
-    params: paramsFromSegments(r.segments),
-  }));
+  const routes = routeFiles
+    .map((r) => ({
+      pattern: patternToColon(r.urlPattern),
+      params: paramsFromSegments(r.segments),
+      filePath: r.filePath,
+    }))
+    // Deterministic order independent of filesystem scan order, so the output
+    // is byte-identical across machines (and the idempotent write works).
+    .sort((a, b) => a.pattern.localeCompare(b.pattern));
 
   const union = routes.length > 0
     ? routes.map((r) => {
@@ -180,11 +289,18 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
 
   // `RouteSearchParamsMap` / `RouteContextMap` are imported from the package so
   // the local `SearchParams<T>` / `Context<T>` reference the same interfaces the
-  // user augments via `declare module "@bractjs/bractjs"`.
-  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs";';
+  // user augments via `declare module "@bractjs/bractjs"`. `InferSchemaOutput`
+  // derives each route's validated search shape from its `searchSchema` export.
+  const IMPORTS = 'import type { RouteSearchParamsMap, RouteContextMap, InferSchemaOutput } from "@bractjs/bractjs";';
+
+  // Freshness breadcrumb: lets the dev server detect drift without re-deriving
+  // the whole file, and lets writeRouteTypes skip identical writes.
+  const fingerprint = await routesFingerprint(routes.map((r) => r.pattern));
+  const FINGERPRINT = `// bractjs:routes ${fingerprint} (${routes.length} route${routes.length === 1 ? "" : "s"})`;
 
   return [
     HEADER,
+    FINGERPRINT,
     IMPORTS,
     "",
     "export type AppRoutes =",
@@ -194,16 +310,24 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     "",
     searchParamsTypeLines(routes),
     "",
+    searchOutputTypeLines(routes),
+    "",
     contextTypeLines(routes),
     "",
     "export type TypedLoaderArgs<T extends AppRoutes> = {",
     "  request: Request;",
     "  params: RouteParams<T>;",
     "  context: Context<T>;",
+    "  search: T extends keyof GeneratedSearchOutput ? GeneratedSearchOutput[T] : Record<string, unknown>;",
     "};",
     "export type TypedActionArgs<T extends AppRoutes> =",
     "  TypedLoaderArgs<T> & { formData: FormData };",
     "",
+    "/** Loader args fully typed for a route literal: `loader(args: LoaderArgsFor<\"/posts\">)`. */",
+    "export type LoaderArgsFor<T extends AppRoutes> = TypedLoaderArgs<T>;",
+    "/** Action args fully typed for a route literal: `action(args: ActionArgsFor<\"/posts\">)`. */",
+    "export type ActionArgsFor<T extends AppRoutes> = TypedActionArgs<T>;",
+    "",
     "/** A locale-prefixed variant of a route (E2 i18n routing). */",
     "export type LocalizedRoute<T extends AppRoutes> = `/${string}${T}`;",
     "",
@@ -217,8 +341,17 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
   ].join("\n");
 }
 
-export async function writeRouteTypes(appDir: string, outPath?: string): Promise<void> {
+export async function writeRouteTypes(
+  appDir: string,
+  outPath?: string,
+): Promise<{ dest: string; written: boolean }> {
   const dest = outPath ?? join(appDir, "route-types.gen.ts");
-  await Bun.write(dest, await generateRouteTypes(appDir));
+  const next = await generateRouteTypes(appDir);
+  // Skip the write (and the log, and the resulting file-watcher event) when the
+  // content is unchanged — otherwise auto-codegen in dev would loop the editor.
+  const existing = await Bun.file(dest).text().catch(() => null);
+  if (existing === next) return { dest, written: false };
+  await Bun.write(dest, next);
   console.log("[bract] codegen →", dest);
+  return { dest, written: true };
 }

package/src/config/load.ts

@@ -25,6 +25,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("appDir", typeof c.appDir === "string", "a string");
   check("publicDir", typeof c.publicDir === "string", "a string");
   check("buildDir", typeof c.buildDir === "string", "a string");
@@ -45,10 +46,30 @@ export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
   check("onStart", typeof c.onStart === "function", "a function");
   check("onShutdown", typeof c.onShutdown === "function", "a function");
   check("onError", typeof c.onError === "function", "a function");
+  check("ssr", typeof c.ssr === "boolean", "a boolean");
+  check(
+    "prerender",
+    typeof c.prerender === "function" ||
+      (Array.isArray(c.prerender) && c.prerender.every((p) => typeof p === "string")),
+    "an array of paths or a function returning one",
+  );
 
   return c as Partial<BractJSConfig>;
 }
 
+/**
+ * Identity helper for `bractjs.config.ts` — wrap your default export to get
+ * autocomplete and type-checking on the config fields (no runtime effect):
+ *
+ * ```ts
+ * import { defineConfig } from "@bractjs/bractjs";
+ * export default defineConfig({ port: 3000, clientEnv: ["PUBLIC_API_URL"] });
+ * ```
+ */
+export function defineConfig(config: Partial<BractJSConfig>): Partial<BractJSConfig> {
+  return config;
+}
+
 /**
  * Load `bractjs.config.ts` (or `.js`) from the user's cwd if present.
  * Returns an empty object when no file exists — callers fall back to defaults.

package/src/dev/hmr-client.ts

@@ -23,7 +23,9 @@ export const hmrClientScript: string = `
   }
 
   function connect() {
-    var ws = new WebSocket("ws://localhost:3001");
+    // Port published by the server's dev bootstrap (config hmrPort), else 3001.
+    var port = window.__BRACTJS_HMR_PORT__ || 3001;
+    var ws = new WebSocket("ws://localhost:" + port);
     ws.onmessage = function (event) {
       try {
         var msg = JSON.parse(event.data);

package/src/dev/route-table.ts

@@ -0,0 +1,27 @@
+export interface RouteTableRow {
+  pattern: string;
+  file: string;
+  hasLoader: boolean;
+  hasAction: boolean;
+}
+
+/**
+ * Render a compact route inventory for the dev server boot log, so a developer
+ * can see at a glance what routes the app matched (and which have data/mutation
+ * handlers). Pure string formatting — no I/O.
+ */
+export function formatRouteTable(rows: RouteTableRow[]): string {
+  if (rows.length === 0) return "[bractjs] no routes found under routes/";
+  const sorted = [...rows].sort((a, b) => a.pattern.localeCompare(b.pattern));
+  const patternWidth = Math.max(7, ...sorted.map((r) => r.pattern.length));
+  const lines = sorted.map((r) => {
+    const markers = [r.hasLoader ? "loader" : "", r.hasAction ? "action" : ""]
+      .filter(Boolean)
+      .join(" ");
+    return `  ${r.pattern.padEnd(patternWidth)}  ${markers.padEnd(13)} ${r.file}`;
+  });
+  return [
+    `[bractjs] ${rows.length} route${rows.length === 1 ? "" : "s"}:`,
+    ...lines,
+  ].join("\n");
+}

package/src/dev/server.ts

@@ -1,13 +1,66 @@
 import { createServer } from "../server/serve.ts";
-import { setRuntimeMode } from "../server/env.ts";
+import { setRuntimeMode, setDevHmrPort } from "../server/env.ts";
 import { createHmrServer } from "./hmr-server.ts";
 import { watchApp } from "./watcher.ts";
 import { rebuildClient } from "./rebuilder.ts";
-import { filePathToPattern } from "../server/scanner.ts";
-import { basename, extname } from "node:path";
+import { filePathToPattern, scanRoutes } from "../server/scanner.ts";
+import { basename, extname, join, resolve } from "node:path";
 import type { LifecycleHooks } from "../server/lifecycle.ts";
 import { loadUserConfig } from "../config/load.ts";
 import type { BractJSConfig } from "../server/serve.ts";
+import { writeRouteTypes, explainStalenessForApp } from "../codegen/route-codegen.ts";
+import { lintRouteModuleSource } from "../build/route-lint.ts";
+import { formatRouteTable, type RouteTableRow } from "./route-table.ts";
+
+// Warn-once across HMR rebuilds so the same lint message doesn't spam the log.
+const warnedRouteIssues = new Set<string>();
+
+/**
+ * Statically lint route modules and print the route table. Reads each route
+ * file's source once (no module execution, no per-request cost). Returns the
+ * table rows so the boot path can print them alongside the HMR port.
+ */
+async function inspectRoutes(appDir: string): Promise<RouteTableRow[]> {
+  const routes = await scanRoutes(appDir);
+  const rows: RouteTableRow[] = [];
+  for (const r of routes) {
+    let src = "";
+    try {
+      src = await Bun.file(resolve(process.cwd(), appDir, r.filePath)).text();
+    } catch {
+      continue;
+    }
+    for (const warning of lintRouteModuleSource(src, r.filePath)) {
+      const key = r.filePath + "\0" + warning;
+      if (warnedRouteIssues.has(key)) continue;
+      warnedRouteIssues.add(key);
+      console.warn(`[bractjs] ${warning}`);
+    }
+    rows.push({
+      pattern: r.urlPattern === "" ? "/" : "/" + r.urlPattern,
+      file: r.filePath,
+      hasLoader: /^export\s+(?:async\s+)?function\s+loader\b|^export\s+const\s+loader\b/m.test(src),
+      hasAction: /^export\s+(?:async\s+)?function\s+action\b|^export\s+const\s+action\b/m.test(src),
+    });
+  }
+  return rows;
+}
+
+/**
+ * Regenerate typed routes if the route set drifted from the last codegen.
+ * Idempotent: writeRouteTypes skips the write when content is unchanged, so it
+ * never triggers an editor reload loop. Runs at boot and on add/remove/rename.
+ */
+async function syncRouteTypes(appDir: string): Promise<void> {
+  try {
+    const reason = await explainStalenessForApp(appDir);
+    if (reason) console.log(`[bractjs] ${reason}`);
+    await writeRouteTypes(appDir);
+  } catch (err) {
+    // Codegen is a DX aid, never fatal to the dev loop.
+    console.warn("[bractjs] route codegen skipped:", err instanceof Error ? err.message : err);
+  }
+}
 
 export interface DevServerOptions {
   /** HTTP port for the app server. Default: config.port ?? 3000. */
@@ -38,15 +91,42 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
   // for any source-import path, dev or `bractjs start`), so no separate dev hook
   // is needed here.
 
-  const hmrPort = options?.hmrPort ?? 3001;
+  const hmrPort = options?.hmrPort ?? merged.hmrPort ?? 3001;
   const appPort = options?.port ?? merged.port ?? 3000;
+  // Publish the port so the SSR dev bootstrap tells the HMR client where to connect.
+  setDevHmrPort(hmrPort);
+
+  const appDir = merged.appDir ?? "./app";
 
-  const hmr = createHmrServer(hmrPort);
+  // Keep typed routes fresh on boot (covers "added a route while the server was
+  // down"). Idempotent — no-op write when nothing changed.
+  await syncRouteTypes(appDir);
+
+  // Friendly port-conflict message instead of a raw Bun EADDRINUSE stack.
+  const onPortInUse = (which: "app server" | "HMR socket", port: number): never => {
+    console.error(
+      `[bractjs] Port ${port} is already in use (${which}). ` +
+        `Set \`port\` (and \`hmrPort\` for the HMR socket) in bractjs.config.ts, ` +
+        `or stop the process using it.`,
+    );
+    return process.exit(1);
+  };
+
+  let hmr: ReturnType<typeof createHmrServer>;
+  try {
+    hmr = createHmrServer(hmrPort);
+  } catch (err) {
+    if ((err as { code?: string }).code === "EADDRINUSE") onPortInUse("HMR socket", hmrPort);
+    throw err;
+  }
 
   // Build client bundle before the HTTP server starts accepting requests
   const { duration: initialMs } = await rebuildClient(merged);
   console.log(`[bractjs] initial client build in ${initialMs}ms`);
 
+  // Lint route modules + collect the route table (read sources once, no exec).
+  const routeRows = await inspectRoutes(appDir);
+
   // Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
   let lifecycle: LifecycleHooks = {};
   try {
@@ -57,9 +137,26 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
     // No lifecycle file — that's fine
   }
 
-  const srv = createServer({ port: appPort, ...merged, ...lifecycle });
+  let srv: ReturnType<typeof createServer>;
+  try {
+    srv = createServer({ port: appPort, ...merged, ...lifecycle });
+  } catch (err) {
+    hmr.stop();
+    if ((err as { code?: string }).code === "EADDRINUSE") onPortInUse("app server", appPort);
+    throw err;
+  }
+
+  watchApp(appDir, async (file, info) => {
+    // Add/remove/rename of a route file changes the route set → regenerate
+    // typed routes. Saves (content changes) never alter the generated output
+    // (it uses type-only `typeof import(...)`), so skip codegen on those.
+    if (info.renameSeen && file.startsWith("routes/")) {
+      await syncRouteTypes(appDir);
+    }
+
+    // Re-lint changed route modules (warn-once dedupes repeats).
+    if (file.startsWith("routes/")) await inspectRoutes(appDir);
 
-  watchApp(merged.appDir ?? "./app", async (file) => {
     const { duration } = await rebuildClient(merged);
 
     // Route files (not layout): do a fine-grained module swap without full reload.
@@ -81,7 +178,8 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
     }
   });
 
-  console.log(`BractJS dev server on http://localhost:${appPort}`);
+  console.log(formatRouteTable(routeRows));
+  console.log(`BractJS dev server on http://localhost:${appPort} (HMR ws://localhost:${hmrPort})`);
 
   return {
     stop() {

package/src/dev/watcher.ts

@@ -3,21 +3,42 @@ import { watch } from "node:fs";
 
 const WATCHED_EXTENSIONS = new Set([".tsx", ".ts", ".css"]);
 
+/** Extra info about a debounced change burst. */
+export interface WatchChangeInfo {
+  /** The last file event type seen in the burst. */
+  event: "rename" | "change";
+  /**
+   * True when ANY event in the burst was a "rename" (add/remove/rename) — not
+   * just the last one. `fs.watch` collapses bursts, so this is OR-accumulated
+   * across the debounce window; the codegen trigger keys on it.
+   */
+  renameSeen: boolean;
+}
+
 /**
  * Watches appDir for file changes and calls onChange with the changed file path.
  * Debounces rapid changes within 50ms to avoid duplicate rebuilds.
  */
-export function watchApp(appDir: string, onChange: (file: string) => void): void {
+export function watchApp(
+  appDir: string,
+  onChange: (file: string, info: WatchChangeInfo) => void,
+): void {
   let debounceTimer: ReturnType<typeof setTimeout> | null = null;
   let pendingFile = "";
+  let lastEvent: "rename" | "change" = "change";
+  let renameSeen = false;
 
-  watch(appDir, { recursive: true }, (_eventType, filename) => {
+  watch(appDir, { recursive: true }, (eventType, filename) => {
     if (!filename) return;
 
     const ext = path.extname(filename);
     if (!WATCHED_EXTENSIONS.has(ext)) return;
 
     pendingFile = filename;
+    lastEvent = eventType === "rename" ? "rename" : "change";
+    // OR-accumulate across the debounce window: a save (change) immediately
+    // followed by a create (rename) must not lose the rename signal.
+    if (lastEvent === "rename") renameSeen = true;
 
     if (debounceTimer !== null) {
       clearTimeout(debounceTimer);
@@ -26,7 +47,8 @@ export function watchApp(appDir: string, onChange: (file: string) => void): void
     debounceTimer = setTimeout(() => {
       debounceTimer = null;
       console.log(`✓ ${path.basename(pendingFile)} changed`);
-      onChange(pendingFile);
+      onChange(pendingFile, { event: lastEvent, renameSeen });
+      renameSeen = false;
     }, 50);
   });
 }

package/src/index.ts

@@ -5,8 +5,11 @@ 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 { validate, safeValidate, isValidationResponse, readValidationError } from "./server/validate.ts";
+export type { FieldErrors, ValidationError, SafeValidateResult } from "./server/validate.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";
 
@@ -70,6 +73,11 @@ export type {
   MetaFunction,
   RouteModule,
   RouteDefinition,
+  RouterLocation,
+  ShouldRevalidateArgs,
+  ShouldRevalidateFunction,
+  LoaderData,
+  ActionData,
 } from "./shared/route-types.ts";
 export type { RouteFile, Segment } from "./server/scanner.ts";
 
@@ -102,17 +110,28 @@ 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 { 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 +146,8 @@ export type {
   RegisteredRoutes,
   ParamsFor,
   SearchFor,
+  SearchOutputFor,
+  InferSchemaOutput,
   RouteSearchParamsMap,
   RouteContextMap,
 } from "./client/registry.ts";
@@ -141,4 +162,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,15 +1,24 @@
 import { resolveAction } from "./action-registry.ts";
 import { json } from "./response.ts";
-import { isAllowedMutation } from "./csrf.ts";
+import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.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 (depth > 20 || !value || typeof value !== "object") return false;
+  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;
@@ -23,7 +32,7 @@ export async function handleActionRequest(request: Request): Promise<Response |
   // 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 });