@bractjs/bractjs 0.1.27 → 0.1.28

package/src/server/action-registry.ts

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

package/src/server/csp.ts

@@ -21,6 +21,15 @@ export interface CspOptions {
    * Useful for staging a policy before turning it on. Default: false.
    */
   reportOnly?: boolean;
+  /**
+   * Drop `'unsafe-inline'` from the default `style-src`. The baseline policy
+   * allows inline styles for ergonomics (React inline styles, CSS-in-JS), which
+   * leaves inline-style injection (CSS exfiltration / UI redress) possible.
+   * Set `strict: true` for `style-src 'self'` only — you must then serve all
+   * styles from same-origin stylesheets (or override `style-src` yourself with
+   * a nonce/hash via `directives`). Default: false.
+   */
+  strict?: boolean;
 }
 
 /**
@@ -70,7 +79,7 @@ export function csp(options: CspOptions = {}): MiddlewareFn {
       // imports without each chunk needing its own nonce. Falls back to 'self'
       // in browsers that don't support it.
       "script-src": `'self' 'nonce-${nonce}' 'strict-dynamic'`,
-      "style-src": "'self' 'unsafe-inline'",
+      "style-src": options.strict ? "'self'" : "'self' 'unsafe-inline'",
       "img-src": "'self' data: blob:",
       "connect-src": "'self'",
       "base-uri": "'self'",

package/src/server/csrf.ts

@@ -29,6 +29,32 @@
 // 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.
+import { isExplicitDev } from "./env.ts";
+
+/**
+ * The developer-facing explanation of a CSRF rejection. In dev it spells out
+ * the accepted signals and the usual fix; in prod it stays terse so the 403
+ * leaks nothing. Used for the plain route/action 403 bodies — the stream
+ * handler embeds {@link csrfHint} in its SSE error event instead.
+ */
+export function csrfHint(): string {
+  return (
+    "Blocked a cross-site or unattributed mutation (CSRF protection). " +
+    "Same-origin browser requests are allowed automatically; a manual fetch() " +
+    'must send the header `X-BractJS-Action: 1` (BractJS\'s <Form> and ' +
+    "useFetcher do this for you)."
+  );
+}
+
+/** A 403 Response for a rejected mutation: explanatory in dev, terse in prod. */
+export function csrfForbiddenResponse(): Response {
+  if (isExplicitDev()) {
+    console.warn("[bractjs] 403 (CSRF): " + csrfHint());
+    return new Response("Forbidden — " + csrfHint(), { status: 403 });
+  }
+  return new Response("Forbidden", { status: 403 });
+}
+
 export function isAllowedMutation(request: Request): boolean {
   // (1) Browser-enforced signal. If present, it vetoes cross-origin requests
   // regardless of what the Origin/custom headers claim.

package/src/server/env.ts

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

package/src/server/layout.ts

@@ -8,6 +8,12 @@ export interface LayoutChain {
   root: RouteModule;
   layouts: RouteModule[];
   route: RouteModule;
+  /**
+   * appDir-relative source paths for each module in the chain, for error
+   * messages ("loader error in routes/blog/[id].tsx"). Optional so hand-built
+   * chains in tests don't have to supply it.
+   */
+  files?: { root?: string; layouts: string[]; route?: string };
 }
 
 export interface ResolvedRoute extends RouteFile {
@@ -102,6 +108,14 @@ export async function importRouteModule(filePath: string): Promise<RouteModule>
     // full-page GET, POST actions, and the /_data soft-nav endpoint alike.
     beforeLoad: mod.beforeLoad,
     context: mod.context,
+    // searchSchema gates loader input — dropping it silently skips search
+    // validation, so loaders would see raw strings where they expect coerced data.
+    searchSchema: mod.searchSchema,
+    // Selective-SSR surface: dropping `ssr` would silently restore full SSR
+    // (running loaders the route opted out of); dropping `Fallback` would
+    // SSR an empty outlet and guarantee a hydration mismatch.
+    ssr: mod.ssr,
+    Fallback: mod.Fallback,
     handle: mod.handle,
     ErrorBoundary: mod.ErrorBoundary,
     default: mod.default,
@@ -124,6 +138,11 @@ function pickRouteModule(mod: Record<string, unknown> | RouteModule | undefined)
     // note in importRouteModule. The compiled-binary path goes through here.
     beforeLoad: m.beforeLoad as RouteModule["beforeLoad"],
     context: m.context as unknown,
+    // Keep searchSchema too — see importRouteModule. Missing it here would
+    // skip search validation only in compiled binaries, the worst kind of skew.
+    searchSchema: m.searchSchema,
+    ssr: m.ssr as RouteModule["ssr"],
+    Fallback: m.Fallback as RouteModule["Fallback"],
     handle: m.handle as RouteModule["handle"],
     ErrorBoundary: m.ErrorBoundary as RouteModule["ErrorBoundary"],
     default: m.default as RouteModule["default"],
@@ -155,7 +174,12 @@ export async function resolveRouteChain(
     const layoutMods = layoutKeys.map((k) => pickRouteModule(registry[k]));
     const routeKey = routeFile.filePath.split("\\").join("/");
     const routeMod = pickRouteModule(registry[routeKey]);
-    return { root: rootMod, layouts: layoutMods, route: routeMod };
+    return {
+      root: rootMod,
+      layouts: layoutMods,
+      route: routeMod,
+      files: { root: rootKey, layouts: layoutKeys, route: routeKey },
+    };
   }
 
   const resolved = await resolveLayoutChain(routeFile, appDir);
@@ -167,9 +191,15 @@ export async function resolveRouteChain(
     resolve(join(appDir, routeFile.filePath))
   );
 
+  // Relativize the absolute layout paths back to appDir-relative for messages.
+  const appRoot = resolve(appDir);
+  const rel = (abs: string) => abs.startsWith(appRoot + "/") ? abs.slice(appRoot.length + 1) : abs;
+  const [rootFile, ...layoutFiles] = resolved.layoutFiles.map(rel);
+
   return {
     root: rootMod ?? {},
     layouts: layoutMods,
     route: routeMod,
+    files: { root: rootFile, layouts: layoutFiles, route: routeFile.filePath },
   };
 }

package/src/server/loader.ts

@@ -21,6 +21,7 @@ export async function safeRun<T>(
   fn: ((args: LoaderArgs) => Promise<T> | T) | undefined,
   args: LoaderArgs,
   onError?: OnErrorHook,
+  where?: string,
 ): Promise<T | { __error: unknown } | null> {
   if (!fn) return null;
 
@@ -36,12 +37,14 @@ export async function safeRun<T>(
     // dev we surface the real message + stack for DX. Routes wanting to
     // surface structured user-facing errors should throw an HttpError, not
     // a custom Error subclass.
-    console.error("[bractjs] loader error:", err);
+    // Name the failing module so the log/overlay points at the right file.
+    console.error(`[bractjs] loader error${where ? ` in ${where}` : ""}:`, err);
     await fireOnError(onError, err, args.request);
     const safe = isExplicitDev()
       ? {
           message: err instanceof Error ? err.message : String(err),
           stack: err instanceof Error ? err.stack : undefined,
+          routeFile: where,
         }
       : { message: "Internal Server Error" };
     return { __error: safe };
@@ -60,7 +63,7 @@ export async function runBeforeLoad(
   args: LoaderArgs,
 ): Promise<Response | null> {
   const fn = routeModule.beforeLoad as
-    | ((a: { params: Record<string,string>; context: Record<string,unknown>; location: { pathname: string; search: string } }) => unknown)
+    | ((a: { params: Record<string,string>; context: Record<string,unknown>; location: { pathname: string; search: string }; search?: Record<string, unknown> }) => unknown)
     | undefined;
   if (!fn) return null;
   const url = new URL(args.request.url);
@@ -68,6 +71,7 @@ export async function runBeforeLoad(
     params: args.params,
     context: args.context,
     location: { pathname: url.pathname, search: url.search },
+    search: args.search,
   });
   if (result instanceof Response) return result;
   return null;
@@ -83,13 +87,14 @@ export async function runLoaders(
   // Run every loader in the chain concurrently — root, all layouts, and the
   // route loader. The route loader is usually the slowest and most important
   // one, so it must not be serialized behind the layout wave.
-  const layoutLoaders = chain.layouts.map((mod) =>
-    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError)
+  const files = chain.files;
+  const layoutLoaders = chain.layouts.map((mod, i) =>
+    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.layouts[i])
   );
 
   const [root, route, ...layoutResults] = await Promise.all([
-    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
-    safeRun(chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
+    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.root),
+    safeRun(chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError, files?.route),
     ...layoutLoaders,
   ]);
 
@@ -118,9 +123,10 @@ export async function runAction(
 export function buildLoaderArgs(
   request: Request,
   params: Record<string, string>,
-  context: Record<string, unknown>
+  context: Record<string, unknown>,
+  search: Record<string, unknown> = {},
 ): LoaderArgs {
-  return { request, params, context };
+  return { request, params, context, search };
 }
 
 // ── runRouteContext ────────────────────────────────────────────────────────

package/src/server/render.ts

@@ -1,7 +1,7 @@
 import { renderToReadableStream } from "react-dom/server";
 import { createElement, Fragment, type ReactNode } from "react";
 import type { MetaDescriptor } from "../shared/route-types.ts";
-import { safeStringify, isDevRuntime } from "./env.ts";
+import { safeStringify, isDevRuntime, getDevHmrPort } from "./env.ts";
 import { errorOverlayScript } from "../dev/error-overlay.ts";
 import { mergeMeta } from "./meta.ts";
 import { MetaTags } from "../shared/meta-tags.tsx";
@@ -18,6 +18,8 @@ export interface RenderOptions {
   actionData: unknown;
   params: Record<string, string>;
   pathname: string;
+  /** Validated search params — hydrates `useSearch()` so the client never re-validates. */
+  search?: Record<string, unknown>;
   manifest: ServerManifest;
   meta: MetaDescriptor[];
   status?: number;
@@ -25,6 +27,13 @@ export interface RenderOptions {
   routeFile?: string;
   /** Per-request CSP nonce (set by the opt-in `csp()` middleware). Applied to the inline bootstrap script + client entry module tags. */
   nonce?: string;
+  /**
+   * Set when the document did NOT SSR the route component: the client renders
+   * the Fallback during hydration, then swaps in the real component
+   * ("data-only": data already present; "client-only": after a /_data fetch;
+   * "spa": static shell, everything resolved client-side).
+   */
+  ssrMode?: "client-only" | "data-only" | "spa";
 }
 
 export async function renderRoute(options: RenderOptions): Promise<Response> {
@@ -38,13 +47,19 @@ export async function renderRoute(options: RenderOptions): Promise<Response> {
     status = 200,
   } = options;
 
-  const devFlag = isDevRuntime() ? "window.__BRACT_DEV__=true;" : "";
+  // In dev, publish the HMR port so the injected client connects to the
+  // configured `hmrPort` rather than a hardcoded 3001. 0 → omit (client
+  // defaults to 3001).
+  const hmrPort = isDevRuntime() ? getDevHmrPort() : 0;
+  const devFlag = isDevRuntime()
+    ? "window.__BRACT_DEV__=true;" + (hmrPort ? `window.__BRACTJS_HMR_PORT__=${hmrPort};` : "")
+    : "";
   const devOverlay = isDevRuntime() ? devFlag + errorOverlayScript + "\n" : "";
   const mergedMeta = mergeMeta(options.meta ?? []);
   // 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, manifest, routeFile: options.routeFile, meta: mergedMeta })};`;
+    devOverlay + `window.__BRACTJS_DATA__=${safeStringify({ loaderData, actionData, params, pathname, search: options.search, manifest, routeFile: options.routeFile, meta: mergedMeta, ssrMode: options.ssrMode })};`;
 
   // Render <title>/<meta> elements alongside the app shell. React 19 hoists
   // document-metadata elements into <head> during streaming SSR, so crawlers

package/src/server/request-handler.ts

@@ -3,14 +3,15 @@ import type { TrieNode } from "./matcher.ts";
 import { matchRoute } from "./matcher.ts";
 import { resolveRouteChain, type ModuleRegistry } from "./layout.ts";
 import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad } from "./loader.ts";
+import { validateSearch } from "./search.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
-import { resolveMeta } from "./meta.ts";
+import { resolveMeta, mergeMeta } from "./meta.ts";
 import { json, error, sanitizeRedirect } from "./response.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
 import { isExplicitDev } from "./env.ts";
 import { pipeline, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
-import { isAllowedMutation } from "./csrf.ts";
+import { isAllowedMutation, csrfForbiddenResponse } from "./csrf.ts";
 import { getCspNonce } from "./csp.ts";
 import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
@@ -87,6 +88,10 @@ async function route(
         headers: request.headers,
         method: "GET",
       });
+      // Validate search params before any route work runs — loaders must
+      // never see unvalidated input, and a 400 here is cheaper than a wasted
+      // context-factory/loader run. The thrown 400 Response propagates below.
+      const search = await validateSearch(chain.route.searchSchema, targetUrl);
       // SECURITY(high): /_data must run the same auth/redirect gates as a full
       // page request — otherwise a SPA-style soft navigation to a protected
       // route would bypass beforeLoad() / defineContext() and leak loader data.
@@ -96,13 +101,20 @@ async function route(
         match.params,
         context,
       );
-      const args = buildLoaderArgs(loaderRequest, match.params, routeContext);
+      const args = buildLoaderArgs(loaderRequest, match.params, routeContext, search);
       const beforeLoadResponse = await runBeforeLoad(chain.route, args);
       if (beforeLoadResponse) return beforeLoadResponse;
       const results = await runLoaders(chain, args, onError);
-      return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
+      // Merged meta must ride along: ClientRouter re-renders the document head
+      // from this payload on soft navigation, and the initial __BRACTJS_DATA__
+      // already carries the merged shape.
+      const meta = mergeMeta(resolveMeta(chain, results, match.params));
+      return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params, meta, search });
     } catch (err) {
       if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
+      // A non-redirect Response (e.g. the 400 thrown by search validation)
+      // is the intended reply — pass it through verbatim.
+      if (err instanceof Response) return err;
       if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
       await fireOnError(onError, err, request);
@@ -115,6 +127,17 @@ async function route(
   if (!match) return error("Not Found", 404);
 
   const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
+
+  // Validate search params before any route work (context factory, beforeLoad,
+  // action, loaders) — they all receive the validated object.
+  let search: Record<string, unknown>;
+  try {
+    search = await validateSearch(chain.route.searchSchema, url);
+  } catch (err) {
+    if (err instanceof Response) return err;
+    throw err;
+  }
+
   // Run per-route context factory (defineContext export) before loaders.
   const routeContext = await runRouteContext(
     chain.route as Parameters<typeof runRouteContext>[0],
@@ -122,7 +145,7 @@ async function route(
     match.params,
     context,
   );
-  const args = buildLoaderArgs(request, match.params, routeContext);
+  const args = buildLoaderArgs(request, match.params, routeContext, search);
 
   // ── beforeLoad ────────────────────────────────────────────────────────
   const beforeLoadResponse = await runBeforeLoad(chain.route, args);
@@ -131,7 +154,7 @@ async function route(
   // ── Action (mutating methods) ─────────────────────────────────────────
   let actionData: unknown = null;
   if (MUTATING_METHODS.has(request.method)) {
-    if (!isAllowedMutation(request)) return error("Forbidden", 403);
+    if (!isAllowedMutation(request)) return csrfForbiddenResponse();
     // Reject up front if the client advertises an oversized body.
     const clRaw = request.headers.get("Content-Length");
     if (clRaw) {
@@ -148,6 +171,8 @@ async function route(
     } catch (err) {
       if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
       if (isHttpError(err)) return error(err.message, err.status);
+      // Name the failing route so the log points at the right file.
+      console.error(`[bractjs] action error in ${chain.files?.route ?? match.routeFile.filePath}:`, err);
       await fireOnError(onError, err, request);
       if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
@@ -167,10 +192,20 @@ async function route(
     }
   }
 
+  // ── Selective SSR ─────────────────────────────────────────────────────
+  // `ssr: false` skips the ROUTE loader during document SSR (root/layout
+  // loaders still run — they render the shell). beforeLoad already ran above:
+  // it is the auth gate and must hold for every mode. The client completes
+  // the render via /_data after hydration, where the loader DOES run.
+  const routeSsr = chain.route.ssr ?? true;
+  const loaderChain = routeSsr === false
+    ? { ...chain, route: { ...chain.route, loader: undefined } }
+    : chain;
+
   // ── Loaders ───────────────────────────────────────────────────────────
   let loaderResults;
   try {
-    loaderResults = await runLoaders(chain, args, onError);
+    loaderResults = await runLoaders(loaderChain, args, onError);
   } catch (err) {
     if (isRedirect(err)) return sanitizeRedirect(err as Response, request.url);
     if (isHttpError(err)) return error(err.message, err.status);
@@ -187,7 +222,10 @@ async function route(
 
   // ── SSR render ────────────────────────────────────────────────────────
   const RootComponent = chain.root.default ?? (() => null);
-  const RouteComponent = chain.route.default;
+  // Non-default SSR modes render the Fallback (or nothing) in the component's
+  // place; the client swaps in the real component after hydration.
+  const RouteComponent = routeSsr === true ? chain.route.default : chain.route.Fallback;
+  const ssrMode = routeSsr === true ? undefined : routeSsr === false ? "client-only" as const : "data-only" as const;
 
   // Wrap root in BractJSProvider so <Outlet> can render the route component
   // server-side without needing a ClientRouter.
@@ -201,6 +239,8 @@ async function route(
         pathname,
         manifest: manifest as unknown as import("../shared/context.ts").RouteManifest,
         RouteComponent,
+        location: { pathname, search: url.search, hash: "", state: null, key: "default" },
+        search,
       },
       children: createElement(RootComponent),
     },
@@ -214,10 +254,12 @@ async function route(
     actionData,
     params: match.params,
     pathname,
+    search,
     manifest,
     meta,
     routeFile: match.routeFile.filePath,
     // Set by the opt-in csp() middleware; undefined otherwise.
     nonce: getCspNonce(context),
+    ssrMode,
   });
 }

package/src/server/search.ts

@@ -0,0 +1,43 @@
+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[]> {
+  const out: 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);
+}