@bractjs/bractjs 0.1.6 → 0.1.8

package/src/client/hooks/useFetcher.ts

@@ -16,10 +16,70 @@ interface FetcherResult {
   submit(path: string, opts: SubmitOptions): Promise<void>;
 }
 
+interface StreamFetcherResult<T = unknown> {
+  events: AsyncGenerator<T>;
+  connect(actionId: string): AsyncGenerator<T>;
+}
+
+// ── SSE async generator ────────────────────────────────────────────────────
+
+async function* sseStream<T>(actionId: string): AsyncGenerator<T> {
+  // Send X-BractJS-Action so the server's CSRF gate accepts this same-origin
+  // GET. Cross-origin <script>/<img>/<link rel=prefetch> tags cannot set this
+  // header, so the gate blocks CSRF invocations of server actions.
+  const res = await fetch(`/_stream?id=${encodeURIComponent(actionId)}`, {
+    headers: { "X-BractJS-Action": "1" },
+  });
+  if (!res.ok || !res.body) {
+    throw new Error(`[bractjs] /_stream ${res.status}`);
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buf += decoder.decode(value, { stream: true });
+      const parts = buf.split("\n\n");
+      buf = parts.pop() ?? "";
+      for (const part of parts) {
+        const lines = part.trim().split("\n");
+        let event = "data";
+        let data = "";
+        for (const line of lines) {
+          if (line.startsWith("event: ")) event = line.slice(7).trim();
+          else if (line.startsWith("data: ")) data = line.slice(6);
+        }
+        if (event === "done") return;
+        if (event === "error") throw new Error((JSON.parse(data) as { message: string }).message);
+        if (event === "data" && data) yield JSON.parse(data) as T;
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+
 // ── Hook ───────────────────────────────────────────────────────────────────
 
-export function useFetcher(): FetcherResult {
+export function useFetcher(): FetcherResult;
+export function useFetcher<T>(opts: { stream: true }): StreamFetcherResult<T>;
+export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | StreamFetcherResult<T> {
+  if (opts?.stream) {
+    return {
+      events: (null as unknown) as AsyncGenerator<T>,
+      connect(actionId: string): AsyncGenerator<T> {
+        return sseStream<T>(actionId);
+      },
+    } satisfies StreamFetcherResult<T>;
+  }
+
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const [data, setData] = useState<unknown>(undefined);
+  // eslint-disable-next-line react-hooks/rules-of-hooks
   const [state, setState] = useState<FetcherState>("idle");
 
   async function load(path: string): Promise<void> {
@@ -33,14 +93,14 @@ export function useFetcher(): FetcherResult {
     }
   }
 
-  async function submit(path: string, opts: SubmitOptions): Promise<void> {
+  async function submit(path: string, submitOpts: SubmitOptions): Promise<void> {
     setState("submitting");
     try {
       const body =
-        opts.body instanceof FormData
-          ? opts.body
-          : new URLSearchParams(opts.body as Record<string, string>);
-      const res = await fetch(path, { method: opts.method, body });
+        submitOpts.body instanceof FormData
+          ? submitOpts.body
+          : new URLSearchParams(submitOpts.body as Record<string, string>);
+      const res = await fetch(path, { method: submitOpts.method, body });
       setData(await res.json());
     } finally {
       setState("idle");

package/src/client/hooks/useLocale.ts

@@ -0,0 +1,12 @@
+import { useParams } from "./useParams.ts";
+
+/**
+ * Returns the current locale from URL params.
+ * Works when the router is configured with i18n prefix routes (`/:locale/...`).
+ *
+ * Falls back to `defaultLocale` when no locale param is present (e.g. SSR without locale prefix).
+ */
+export function useLocale(defaultLocale = "en"): string {
+  const params = useParams<{ locale?: string }>();
+  return params.locale ?? defaultLocale;
+}

package/src/client/hooks/useLocalizedLink.ts

@@ -0,0 +1,18 @@
+import { useLocale } from "./useLocale.ts";
+
+/**
+ * Returns a helper that prepends the current locale to a path.
+ *
+ * Usage:
+ *   const localizedTo = useLocalizedLink();
+ *   <Link to={localizedTo('/about')} />  // → /en/about
+ */
+export function useLocalizedLink(defaultLocale = "en"): (path: string) => string {
+  const locale = useLocale(defaultLocale);
+  return (path: string) => {
+    // Don't double-prefix if the path already starts with /<locale>.
+    const alreadyPrefixed = path.startsWith(`/${locale}/`) || path === `/${locale}`;
+    if (alreadyPrefixed) return path;
+    return `/${locale}${path.startsWith("/") ? path : "/" + path}`;
+  };
+}

package/src/client/hooks/useSearchParams.ts

@@ -0,0 +1,74 @@
+import { useState, useCallback, useEffect, useRef, startTransition } from "react";
+import { NavigationContext } from "../router.tsx";
+import { useContext } from "react";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+type SetSearchParams = (
+  updater: Record<string, string> | ((prev: URLSearchParams) => URLSearchParams),
+) => void;
+
+export interface SearchParamsResult<T extends Record<string, string>> {
+  searchParams: URLSearchParams;
+  getParam<K extends keyof T & string>(key: K): T[K] | null;
+  setSearchParams: SetSearchParams;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+/**
+ * Reads and writes URL search params, typed per-route via generic T.
+ * Triggers a loader re-run (soft-nav fetch) when params change.
+ *
+ * T is the route's SearchParams shape (e.g. { page: string; sort: string }).
+ * This hook is SSR-safe: on the server window is absent, so it returns empty params.
+ */
+export function useSearchParams<T extends Record<string, string> = Record<string, string>>(): SearchParamsResult<T> {
+  const navCtx = useContext(NavigationContext);
+
+  function readCurrent(): URLSearchParams {
+    if (typeof window === "undefined") return new URLSearchParams();
+    return new URLSearchParams(window.location.search);
+  }
+
+  const [searchParams, setSearchParamsState] = useState<URLSearchParams>(readCurrent);
+
+  // Track whether we triggered the change ourselves to avoid double re-run.
+  const selfTriggerRef = useRef(false);
+
+  // Sync when the browser's history changes (back/forward, external pushState).
+  useEffect(() => {
+    function onPopState() {
+      setSearchParamsState(new URLSearchParams(window.location.search));
+    }
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, []);
+
+  const setSearchParams: SetSearchParams = useCallback((updater) => {
+    const next =
+      typeof updater === "function"
+        ? updater(new URLSearchParams(window.location.search))
+        : new URLSearchParams(updater);
+
+    const newSearch = next.toString();
+    const newUrl = window.location.pathname + (newSearch ? "?" + newSearch : "") + window.location.hash;
+
+    // Update browser URL without pushing a new history entry if only params changed.
+    history.pushState({}, "", newUrl);
+    selfTriggerRef.current = true;
+    startTransition(() => setSearchParamsState(next));
+
+    // Trigger a loader re-run via the NavigationContext navigate so the full
+    // soft-nav fetch path is exercised (meta update, module swap, etc.).
+    if (navCtx) {
+      void navCtx.navigate(window.location.pathname + (newSearch ? "?" + newSearch : ""));
+    }
+  }, [navCtx]);
+
+  const getParam = useCallback(<K extends keyof T & string>(key: K): T[K] | null => {
+    return (searchParams.get(key) as T[K] | null);
+  }, [searchParams]);
+
+  return { searchParams, getParam, setSearchParams };
+}

package/src/client/rpc.ts

@@ -0,0 +1,70 @@
+// ── createClient ───────────────────────────────────────────────────────────
+
+/**
+ * Creates a fully-typed fetch client for BractJS API routes.
+ *
+ * Usage:
+ *   import type { AppApiRoutes } from 'bractjs';
+ *   const client = createClient<AppApiRoutes>();
+ *   const users = await client['/api/users'].GET();
+ *
+ * The proxy builds the fetch URL from the property access chain and HTTP method,
+ * so `client['/api/users'].GET()` calls `GET /api/users`.
+ *
+ * This is intentionally minimal (no batching, no retries) — add wrapping as needed.
+ */
+
+type UnwrapPromise<T> = T extends Promise<infer U> ? U : T;
+
+// Given a union of route definitions (method/path/input/output), extract
+// the output type for a specific method + path pair.
+type RouteOutput<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+  TMethod extends string,
+  TPath extends string,
+> = Extract<TRoutes, { method: TMethod; path: TPath }>["output"];
+
+type RouteInput<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+  TMethod extends string,
+  TPath extends string,
+> = Extract<TRoutes, { method: TMethod; path: TPath }>["input"];
+
+type ApiClient<TRoutes extends { method: string; path: string; input: unknown; output: unknown }> = {
+  [TPath in TRoutes["path"]]: {
+    [TMethod in Extract<TRoutes, { path: TPath }>["method"]]: (
+      input?: RouteInput<TRoutes, TMethod, TPath>,
+    ) => Promise<UnwrapPromise<RouteOutput<TRoutes, TMethod, TPath>>>;
+  };
+};
+
+export function createClient<
+  TRoutes extends { method: string; path: string; input: unknown; output: unknown },
+>(baseUrl = ""): ApiClient<TRoutes> {
+  return new Proxy({} as ApiClient<TRoutes>, {
+    get(_target, path: string) {
+      return new Proxy({} as Record<string, unknown>, {
+        get(_t, method: string) {
+          return async (input?: unknown) => {
+            const httpMethod = method.toUpperCase();
+            const url = baseUrl + path;
+            const hasBody = httpMethod !== "GET" && httpMethod !== "DELETE" && input !== undefined;
+            const res = await fetch(url, {
+              method: httpMethod,
+              headers: hasBody ? { "Content-Type": "application/json" } : undefined,
+              body: hasBody ? JSON.stringify(input) : undefined,
+            });
+            if (!res.ok) {
+              const err = await res.json().catch(() => ({ error: res.statusText }));
+              throw Object.assign(new Error((err as { error?: string }).error ?? res.statusText), {
+                status: res.status,
+                response: res,
+              });
+            }
+            return res.json();
+          };
+        },
+      });
+    },
+  });
+}

package/src/codegen/route-codegen.ts

@@ -78,6 +78,61 @@ const HEADER =
   "\n" +
   "/* eslint-disable */\n";
 
+function searchParamsTypeLines(routes: Array<{ pattern: string }>): string {
+  // Route files may declare `export type SearchParams = { page: string }`.
+  // We emit a mapped type that falls back to Record<string,string> per route.
+  // Users augment via module augmentation or via their route file's export.
+  if (routes.length === 0) {
+    return "export type SearchParams<_T extends AppRoutes> = Record<string, string>;";
+  }
+  const branches = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteSearchParamsMap[" + JSON.stringify(r.pattern) + "] :";
+    })
+    .join("\n");
+  const mapEntries = routes
+    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, string>;")
+    .join("\n");
+  return [
+    "// Augment RouteSearchParamsMap to type search params per route:",
+    "// declare module 'bractjs' { interface RouteSearchParamsMap { '/blog': { page: string } } }",
+    "export interface RouteSearchParamsMap {",
+    mapEntries,
+    "}",
+    "",
+    "export type SearchParams<T extends AppRoutes> =",
+    branches,
+    "  Record<string, string>;",
+  ].join("\n");
+}
+
+function contextTypeLines(routes: Array<{ pattern: string }>): string {
+  if (routes.length === 0) {
+    return "export type Context<_T extends AppRoutes> = Record<string, unknown>;";
+  }
+  const branches = routes
+    .map((r) => {
+      assertSafePattern(r.pattern);
+      return "  T extends " + JSON.stringify(r.pattern) + " ? RouteContextMap[" + JSON.stringify(r.pattern) + "] :";
+    })
+    .join("\n");
+  const mapEntries = routes
+    .map((r) => "  " + JSON.stringify(r.pattern) + ": Record<string, unknown>;")
+    .join("\n");
+  return [
+    "// Augment RouteContextMap to type context per route:",
+    "// declare module 'bractjs' { interface RouteContextMap { '/blog': { user: User } } }",
+    "export interface RouteContextMap {",
+    mapEntries,
+    "}",
+    "",
+    "export type Context<T extends AppRoutes> =",
+    branches,
+    "  Record<string, unknown>;",
+  ].join("\n");
+}
+
 export async function generateRouteTypes(appDir: string): Promise<string> {
   const routeFiles = await scanRoutes(appDir);
   const routes = routeFiles.map((r) => ({
@@ -101,14 +156,21 @@ export async function generateRouteTypes(appDir: string): Promise<string> {
     "",
     paramsTypeLines(routes),
     "",
+    searchParamsTypeLines(routes),
+    "",
+    contextTypeLines(routes),
+    "",
     "export type TypedLoaderArgs<T extends AppRoutes> = {",
     "  request: Request;",
     "  params: RouteParams<T>;",
-    "  context: Record<string, unknown>;",
+    "  context: Context<T>;",
     "};",
     "export type TypedActionArgs<T extends AppRoutes> =",
     "  TypedLoaderArgs<T> & { formData: FormData };",
     "",
+    "/** A locale-prefixed variant of a route (E2 i18n routing). */",
+    "export type LocalizedRoute<T extends AppRoutes> = `/${string}${T}`;",
+    "",
     "export const routes = {",
     builderEntries,
     "} as const;",

package/src/dev/devtools.ts

@@ -0,0 +1,144 @@
+/**
+ * BractJS DevTools Panel (E3).
+ *
+ * In dev mode this module is imported by the HMR client and registers a
+ * `<bractjs-devtools>` custom element.  The element reads shared state from
+ * `window.__BRACTJS_DEVTOOLS__` which is populated by ClientRouter.
+ *
+ * Ctrl+Shift+B toggles the panel.
+ * Zero production overhead — this file is never imported in production because
+ * it is only loaded via `if (__BRACT_DEV__)` in the HMR client.
+ */
+
+export interface DevtoolsState {
+  route: string | null;
+  loaderData: Record<string, unknown>;
+  navState: string;
+  cacheEntries: Array<{ key: string; age: number; staleTime: number; gcTime: number }>;
+  beforeLoadTrace: string[];
+}
+
+declare global {
+  interface Window {
+    __BRACTJS_DEVTOOLS__?: DevtoolsState;
+  }
+}
+
+const PANEL_ID = "bractjs-devtools-panel";
+
+class BractJSDevtools extends HTMLElement {
+  private open = false;
+  private panel: HTMLDivElement | null = null;
+
+  connectedCallback() {
+    this.style.cssText = "position:fixed;bottom:0;right:0;z-index:2147483647;font-family:monospace;";
+
+    const toggle = document.createElement("button");
+    toggle.textContent = "⚡ BractJS";
+    toggle.style.cssText =
+      "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
+    toggle.onclick = () => this.togglePanel();
+    this.appendChild(toggle);
+
+    // Keyboard shortcut
+    document.addEventListener("keydown", (e) => {
+      if (e.ctrlKey && e.shiftKey && e.key === "B") {
+        e.preventDefault();
+        this.togglePanel();
+      }
+    });
+  }
+
+  private togglePanel() {
+    if (this.panel) {
+      this.panel.remove();
+      this.panel = null;
+      this.open = false;
+    } else {
+      this.open = true;
+      this.renderPanel();
+    }
+  }
+
+  private renderPanel() {
+    const state = window.__BRACTJS_DEVTOOLS__ ?? {
+      route: null,
+      loaderData: {},
+      navState: "idle",
+      cacheEntries: [],
+      beforeLoadTrace: [],
+    };
+
+    const panel = document.createElement("div");
+    panel.id = PANEL_ID;
+    panel.style.cssText =
+      "background:#1e1e1e;color:#ccc;width:480px;max-height:60vh;overflow:auto;" +
+      "border-top:2px solid #61dafb;border-left:2px solid #61dafb;padding:12px;font-size:11px;";
+
+    const header = document.createElement("div");
+    header.style.cssText = "color:#61dafb;font-weight:bold;margin-bottom:8px;font-size:13px;";
+    header.textContent = "BractJS DevTools";
+    panel.appendChild(header);
+
+    this.section(panel, "Route", state.route ?? "(none)");
+    this.section(panel, "Navigation state", state.navState);
+    this.section(panel, "Loader data", JSON.stringify(state.loaderData, null, 2));
+
+    if (state.cacheEntries.length > 0) {
+      const cacheText = state.cacheEntries
+        .map((e) => `${e.key}\n  age=${e.age}ms stale=${e.staleTime}ms gc=${e.gcTime}ms`)
+        .join("\n");
+      this.section(panel, `Cache (${state.cacheEntries.length})`, cacheText);
+    }
+
+    if (state.beforeLoadTrace.length > 0) {
+      this.section(panel, "beforeLoad trace", state.beforeLoadTrace.join("\n"));
+    }
+
+    this.panel = panel;
+    this.appendChild(panel);
+
+    // Auto-refresh every second while open.
+    const timer = setInterval(() => {
+      if (!this.open) { clearInterval(timer); return; }
+      panel.remove();
+      this.panel = null;
+      this.renderPanel();
+    }, 1000);
+  }
+
+  private section(parent: HTMLElement, title: string, content: string) {
+    const h = document.createElement("div");
+    h.style.cssText = "color:#61dafb;margin-top:8px;margin-bottom:2px;";
+    h.textContent = title;
+    parent.appendChild(h);
+
+    const pre = document.createElement("pre");
+    pre.style.cssText = "margin:0;white-space:pre-wrap;word-break:break-all;color:#ccc;";
+    pre.textContent = content;
+    parent.appendChild(pre);
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("bractjs-devtools")) {
+  customElements.define("bractjs-devtools", BractJSDevtools);
+}
+
+/**
+ * Inject the `<bractjs-devtools>` element into the document body.
+ * Called by the HMR client in dev mode.
+ */
+export function injectDevtools(): void {
+  if (typeof document === "undefined") return;
+  if (document.querySelector("bractjs-devtools")) return;
+  const el = document.createElement("bractjs-devtools");
+  document.body.appendChild(el);
+}
+
+/**
+ * Update the shared devtools state object.
+ * Called by ClientRouter on every navigation.
+ */
+export function updateDevtoolsState(state: Partial<DevtoolsState>): void {
+  window.__BRACTJS_DEVTOOLS__ = { ...window.__BRACTJS_DEVTOOLS__, ...state } as DevtoolsState;
+}

package/src/dev/hmr-client.ts

@@ -13,6 +13,15 @@
  */
 export const hmrClientScript: string = `
 (function () {
+  // Inject DevTools panel in dev mode (E3).
+  if (typeof customElements !== 'undefined') {
+    import('/_bractjs/devtools.js').then(function(m) {
+      if (typeof m.injectDevtools === 'function') m.injectDevtools();
+    }).catch(function() {
+      // DevTools module not available — skip silently.
+    });
+  }
+
   function connect() {
     var ws = new WebSocket("ws://localhost:3001");
     ws.onmessage = function (event) {
@@ -21,6 +30,11 @@ export const hmrClientScript: string = `
         if (msg.type === "hmr:reload") {
           location.reload();
         } else if (msg.type === "hmr:route" && msg.pattern != null && msg.chunkUrl) {
+          // Validate chunk URL is a same-origin relative path before importing.
+          // Prevents a compromised/MITM'd dev WS from executing arbitrary URLs.
+          if (typeof msg.chunkUrl !== 'string' || !/^\/build\//.test(msg.chunkUrl)) {
+            return;
+          }
           // Cache-bust so the browser re-fetches the rebuilt chunk.
           // The chunk was built with splitting, so it shares the same React
           // instance as client.js — no dual-React issue.

package/src/dev/hmr-module-handler.ts

@@ -1,5 +1,7 @@
 import { resolve, join, sep } from "node:path";
 import { realpath } from "node:fs/promises";
+import { serverOnlyPlugin } from "../build/env-plugin.ts";
+import { useServerProxyPlugin } from "../build/directives.ts";
 
 /**
  * Dev-only HTTP handler for /_hmr/module?file=routes/about.tsx
@@ -18,6 +20,14 @@ export async function handleHmrModuleRequest(
     return new Response("Missing file param", { status: 400 });
   }
 
+  // SECURITY(high): restrict to JS/TS source files. Without this, /_hmr/module
+  // would build and ship the contents of any file inside appDir (e.g. .env,
+  // .json, .md) as JavaScript to the browser — useful only for compiling
+  // route modules, so allowlist their extensions.
+  if (!/\.(tsx?|jsx?)$/.test(file)) {
+    return new Response("Forbidden", { status: 403 });
+  }
+
   // Resolve and guard against path traversal AND symlink escape.
   const rootDir = resolve(appDir);
   const candidate = resolve(join(rootDir, file));
@@ -34,12 +44,18 @@ export async function handleHmrModuleRequest(
     return new Response("Forbidden", { status: 403 });
   }
 
-  // Build in-memory (no outdir → outputs held in memory, no disk write)
+  // SECURITY(high): apply the same client-bundle guard plugins the production
+  // build uses. Without these, a route module that imports `*.server.ts` or
+  // contains "use server" exports would have that server source compiled and
+  // shipped to the browser as JavaScript over /_hmr/module — leaking
+  // credentials, DB code, etc. The serverOnlyPlugin hard-fails such imports
+  // and useServerProxyPlugin rewrites "use server" exports to fetch stubs.
   const result = await Bun.build({
     entrypoints: [fullPath],
     target: "browser",
     minify: false,
     sourcemap: "inline",
+    plugins: [serverOnlyPlugin, useServerProxyPlugin],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/hmr-server.ts

@@ -18,6 +18,22 @@ export function createHmrServer(port = 3001): {
   const server = Bun.serve({
     port,
     fetch(req, srv) {
+      // SECURITY(medium): reject WebSocket upgrades that don't come from a
+      // loopback Origin. Without this, any website the developer visits could
+      // open a WS to ws://localhost:<port> and receive file paths from HMR
+      // broadcasts (a passive leak of project structure). Same-origin /
+      // missing Origin (curl, native ws clients) are allowed for dev DX.
+      const origin = req.headers.get("Origin");
+      if (origin) {
+        try {
+          const host = new URL(origin).hostname;
+          if (host !== "localhost" && host !== "127.0.0.1" && host !== "[::1]" && host !== "::1") {
+            return new Response("Forbidden", { status: 403 });
+          }
+        } catch {
+          return new Response("Forbidden", { status: 403 });
+        }
+      }
       if (srv.upgrade(req)) return undefined;
       return new Response("HMR WebSocket endpoint", { status: 426 });
     },

package/src/image/handler.ts

@@ -14,8 +14,11 @@ async function parseParams(
   publicDir: string,
 ): Promise<{ src: string; filePath: string; params: ImageTransformParams } | null> {
   const src = sp.get("src");
-  // src must be a /public/ path with no traversal sequences
-  if (!src || !src.startsWith("/public/") || src.includes("..")) return null;
+  // src must be a /public/ path with no ".." path segment. We check segments
+  // (not substring) so filenames like "foo..bar.jpg" are still allowed —
+  // realpath()/prefix check below is the authoritative escape guard.
+  if (!src || !src.startsWith("/public/")) return null;
+  if (src.split("/").includes("..")) return null;
 
   const rel = src.slice("/public/".length);
   const root = resolve(publicDir);

package/src/image/optimizer.ts

@@ -57,9 +57,14 @@ function resizeArgs(params: ImageTransformParams): string[] {
 
 function buildArgs(binary: string, input: string, params: ImageTransformParams): string[] {
   const base = binary === "magick" ? ["magick", "convert"] : ["convert"];
+  // SECURITY(low): prefix the input with `file:` so ImageMagick treats it as
+  // a filesystem path even if it contains a coder prefix like `mvg:` or
+  // `https:` (e.g. an attacker who plants a file named "https:evil.txt"
+  // inside publicDir). Defense in depth — realpath() already constrains the
+  // path to publicDir, so this prevents the "format coder hijack" class only.
   return [
     ...base,
-    input,
+    `file:${input}`,
     ...resizeArgs(params),
     "-quality", String(params.q),
     "-strip",

package/src/index.ts

@@ -1,5 +1,23 @@
 // Server
 export { createServer, renderRoute, redirect, json, error } from "./server/index.ts";
+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 { validate } from "./server/validate.ts";
+export type { FieldErrors, ValidationError } from "./server/validate.ts";
+export type { BractAdapter } from "./server/adapter.ts";
+export { BunAdapter } from "./server/adapter.ts";
+
+// Adapters
+export { createCloudflareAdapter, makeCloudflareHandler } from "./adapters/cloudflare.ts";
+
+// Build plugins
+export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-modules.ts";
+
+// Client RPC
+export { createClient } from "./client/rpc.ts";
 export type { BractJSConfig, RenderOptions, ServerManifest } from "./server/index.ts";
 
 // Shared types
@@ -49,3 +67,12 @@ export { useActionData } from "./client/hooks/useActionData.ts";
 export { useParams } from "./client/hooks/useParams.ts";
 export { useNavigation } from "./client/hooks/useNavigation.ts";
 export { useFetcher } from "./client/hooks/useFetcher.ts";
+export { useSearchParams } from "./client/hooks/useSearchParams.ts";
+export type { SearchParamsResult } from "./client/hooks/useSearchParams.ts";
+export { useBlocker } from "./client/hooks/useBlocker.ts";
+export { useLocale } from "./client/hooks/useLocale.ts";
+export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
+
+// i18n utilities (server-side)
+export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
+export type { I18nConfig } from "./server/serve.ts";