@bractjs/bractjs 0.1.21 → 0.1.23

package/src/server/layout.ts

@@ -14,6 +14,14 @@ export interface ResolvedRoute extends RouteFile {
   layoutFiles: string[];
 }
 
+/**
+ * Pre-loaded module map keyed by appDir-relative path (e.g. "root.tsx",
+ * "routes/blog/layout.tsx"). When `resolveRouteChain` is called with a
+ * registry, all module lookups go through the registry instead of dynamic
+ * `import(absPath)` — this is what makes `bun build --compile` viable.
+ */
+export type ModuleRegistry = Record<string, RouteModule | Record<string, unknown>>;
+
 // ── Helpers ────────────────────────────────────────────────────────────────
 
 /** Derive the ancestor directory segments from a route's urlPattern. */
@@ -55,6 +63,31 @@ export async function resolveLayoutChain(
   return { ...routeFile, layoutFiles };
 }
 
+/**
+ * Registry-driven equivalent of `resolveLayoutChain`. Skips all filesystem
+ * checks — returns the appDir-relative keys that exist in the registry, in
+ * the same root-first, outermost-to-innermost order. Required for compiled
+ * binaries where `Bun.file().exists()` against the original app paths is
+ * unreliable.
+ */
+export function resolveLayoutChainFromRegistry(
+  routeFile: RouteFile,
+  registry: ModuleRegistry,
+): ResolvedRoute {
+  const layoutFiles: string[] = [];
+  if (registry["root.tsx"]) layoutFiles.push("root.tsx");
+  else if (registry["root.ts"]) layoutFiles.push("root.ts");
+
+  for (const dir of layoutDirs(routeFile.urlPattern)) {
+    const tsxKey = `routes/${dir}/layout.tsx`;
+    const tsKey = `routes/${dir}/layout.ts`;
+    if (registry[tsxKey]) layoutFiles.push(tsxKey);
+    else if (registry[tsKey]) layoutFiles.push(tsKey);
+  }
+
+  return { ...routeFile, layoutFiles };
+}
+
 // ── importRouteModule ──────────────────────────────────────────────────────
 
 export async function importRouteModule(filePath: string): Promise<RouteModule> {
@@ -69,12 +102,52 @@ export async function importRouteModule(filePath: string): Promise<RouteModule>
   };
 }
 
+/**
+ * Project a registry entry (raw `import * as ns` namespace) into the
+ * subset shape `RouteModule` requires. Mirrors `importRouteModule` but
+ * skips the dynamic `import()` because the module is already loaded.
+ */
+function pickRouteModule(mod: Record<string, unknown> | RouteModule | undefined): RouteModule {
+  if (!mod) return {};
+  const m = mod as Record<string, unknown>;
+  return {
+    loader: m.loader as RouteModule["loader"],
+    action: m.action as RouteModule["action"],
+    meta: m.meta as RouteModule["meta"],
+    handle: m.handle as RouteModule["handle"],
+    ErrorBoundary: m.ErrorBoundary as RouteModule["ErrorBoundary"],
+    default: m.default as RouteModule["default"],
+  };
+}
+
 // ── resolveRouteChain ──────────────────────────────────────────────────────
 
+/**
+ * Build the route + layout chain for a matched route.
+ *
+ * Two modes:
+ * - Registry mode (production / compiled binary): when `registry` is provided,
+ *   no filesystem checks and no dynamic imports run. Every module lookup is a
+ *   `Record` access keyed by appDir-relative path.
+ * - Dev mode (no registry): existing filesystem-probe + `import(absPath)`
+ *   path, used by `bractjs dev` so edits to layouts/routes don't require a
+ *   codegen rerun.
+ */
 export async function resolveRouteChain(
   routeFile: RouteFile,
-  appDir: string
+  appDir: string,
+  registry?: ModuleRegistry,
 ): Promise<LayoutChain> {
+  if (registry) {
+    const resolved = resolveLayoutChainFromRegistry(routeFile, registry);
+    const [rootKey, ...layoutKeys] = resolved.layoutFiles;
+    const rootMod = rootKey ? pickRouteModule(registry[rootKey]) : {};
+    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 };
+  }
+
   const resolved = await resolveLayoutChain(routeFile, appDir);
 
   const [rootMod, ...layoutMods] = await Promise.all(

package/src/server/lifecycle.ts

@@ -1,9 +1,23 @@
+export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
+
 export interface LifecycleHooks {
   onStart?: () => Promise<void> | void;
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are intentional control flow and are NOT reported here. Use this to send errors to Sentry, Datadog, etc. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
 }
 
 /** Type-safe helper for declaring server lifecycle hooks in app/lifecycle.ts. */
 export function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks {
   return hooks;
 }
+
+/** Safely invokes the onError hook. Errors thrown inside the hook are caught and logged so they never mask the original error or alter the response. */
+export async function fireOnError(hook: OnErrorHook | undefined, err: unknown, request?: Request): Promise<void> {
+  if (!hook) return;
+  try {
+    await hook(err, request);
+  } catch (hookErr) {
+    console.error("[bractjs] onError hook threw:", hookErr);
+  }
+}

package/src/server/loader.ts

@@ -3,6 +3,7 @@ import type { LayoutChain } from "./layout.ts";
 import { isRedirect, isHttpError } from "../shared/errors.ts";
 import { isExplicitDev } from "./env.ts";
 import type { ContextFactory } from "./context.ts";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -18,7 +19,8 @@ export interface LoaderResults {
 
 export async function safeRun<T>(
   fn: ((args: LoaderArgs) => Promise<T> | T) | undefined,
-  args: LoaderArgs
+  args: LoaderArgs,
+  onError?: OnErrorHook,
 ): Promise<T | { __error: unknown } | null> {
   if (!fn) return null;
 
@@ -35,6 +37,7 @@ export async function safeRun<T>(
     // surface structured user-facing errors should throw an HttpError, not
     // a custom Error subclass.
     console.error("[bractjs] loader error:", err);
+    await fireOnError(onError, err, args.request);
     const safe = isExplicitDev()
       ? {
           message: err instanceof Error ? err.message : String(err),
@@ -74,20 +77,22 @@ export async function runBeforeLoad(
 
 export async function runLoaders(
   chain: LayoutChain,
-  args: LoaderArgs
+  args: LoaderArgs,
+  onError?: OnErrorHook,
 ): Promise<LoaderResults> {
   const layoutLoaders = chain.layouts.map((mod) =>
-    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args)
+    safeRun(mod.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError)
   );
 
   const [root, ...layoutResults] = await Promise.all([
-    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args),
+    safeRun(chain.root.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined, args, onError),
     ...layoutLoaders,
   ]);
 
   const route = await safeRun(
     chain.route.loader as ((a: LoaderArgs) => Promise<unknown>) | undefined,
-    args
+    args,
+    onError,
   );
 
   return { root, layouts: layoutResults, route };

package/src/server/request-handler.ts

@@ -1,7 +1,7 @@
 import { createElement } from "react";
 import type { TrieNode } from "./matcher.ts";
 import { matchRoute } from "./matcher.ts";
-import { resolveRouteChain } from "./layout.ts";
+import { resolveRouteChain, type ModuleRegistry } from "./layout.ts";
 import { runLoaders, runAction, buildLoaderArgs, runRouteContext, runBeforeLoad } from "./loader.ts";
 import { renderRoute, type ServerManifest } from "./render.ts";
 import { resolveMeta } from "./meta.ts";
@@ -11,11 +11,19 @@ import { isExplicitDev } from "./env.ts";
 import { pipeline, type MiddlewareContext } from "./middleware.ts";
 import { BractJSProvider } from "../shared/context.ts";
 import { isAllowedMutation } from "./csrf.ts";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 export interface HandlerConfig {
   appDir: string;
   publicDir: string;
   manifest: ServerManifest;
+  onError?: OnErrorHook;
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Provided by codegen (`_generated/routes.ts`) for compiled binaries
+   * where dynamic `import(absPath)` is unavailable. Falsy in dev mode.
+   */
+  moduleRegistry?: ModuleRegistry;
 }
 
 const MUTATING_METHODS = new Set(["POST", "PUT", "DELETE", "PATCH"]);
@@ -45,7 +53,7 @@ async function route(
   config: HandlerConfig,
   context: Record<string, unknown>,
 ): Promise<Response> {
-  const { appDir, manifest } = config;
+  const { appDir, manifest, onError, moduleRegistry } = config;
   const url = new URL(request.url);
   const { pathname, searchParams } = url;
 
@@ -68,7 +76,7 @@ async function route(
     if (!match) return json({ error: "Not Found" }, { status: 404 });
 
     try {
-      const chain = await resolveRouteChain(match.routeFile, appDir);
+      const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
       // Reconstruct a Request that carries the original search params so loaders
       // can access them via request.url / new URL(request.url).searchParams.
       const targetUrl = new URL(request.url);
@@ -90,12 +98,13 @@ async function route(
       const args = buildLoaderArgs(loaderRequest, match.params, routeContext);
       const beforeLoadResponse = await runBeforeLoad(chain.route, args);
       if (beforeLoadResponse) return beforeLoadResponse;
-      const results = await runLoaders(chain, args);
+      const results = await runLoaders(chain, args, onError);
       return json({ root: results.root, layouts: results.layouts, route: results.route, params: match.params });
     } catch (err) {
       if (isRedirect(err)) return err as Response;
       if (isHttpError(err)) return json({ error: err.message }, { status: err.status });
       console.error("[bractjs] /_data error:", err);
+      await fireOnError(onError, err, request);
       return json({ error: "Internal Server Error" }, { status: 500 });
     }
   }
@@ -104,7 +113,7 @@ async function route(
   const match = matchRoute(pathname, trie);
   if (!match) return error("Not Found", 404);
 
-  const chain = await resolveRouteChain(match.routeFile, appDir);
+  const chain = await resolveRouteChain(match.routeFile, appDir, moduleRegistry);
   // Run per-route context factory (defineContext export) before loaders.
   const routeContext = await runRouteContext(
     chain.route as Parameters<typeof runRouteContext>[0],
@@ -138,6 +147,7 @@ async function route(
     } catch (err) {
       if (isRedirect(err)) return err as Response;
       if (isHttpError(err)) return error(err.message, err.status);
+      await fireOnError(onError, err, request);
       if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
       return error("Internal Server Error", 500);
     }
@@ -151,10 +161,11 @@ async function route(
   // ── Loaders ───────────────────────────────────────────────────────────
   let loaderResults;
   try {
-    loaderResults = await runLoaders(chain, args);
+    loaderResults = await runLoaders(chain, args, onError);
   } catch (err) {
     if (isRedirect(err)) return err as Response;
     if (isHttpError(err)) return error(err.message, err.status);
+    await fireOnError(onError, err, request);
     if (isExplicitDev()) return error(err instanceof Error ? err.message : String(err), 500);
     return error("Internal Server Error", 500);
   }

package/src/server/serve.ts

@@ -1,4 +1,4 @@
-import { scanRoutes } from "./scanner.ts";
+import { scanRoutes, type RouteFile } from "./scanner.ts";
 import { buildTrie } from "./matcher.ts";
 import { handleRequest, type HandlerConfig } from "./request-handler.ts";
 import { type ServerManifest } from "./render.ts";
@@ -6,10 +6,12 @@ import { isDevRuntime, isExplicitDev } from "./env.ts";
 import { loadManifest } from "../build/manifest.ts";
 import { serveStatic } from "./static.ts";
 import { handleImageRequest } from "../image/handler.ts";
-import { loadServerActions } from "./action-registry.ts";
+import { loadServerActions, loadServerActionsFromRegistry } from "./action-registry.ts";
 import { handleActionRequest } from "./action-handler.ts";
 import { BunAdapter, type BractAdapter } from "./adapter.ts";
+import type { ModuleRegistry } from "./layout.ts";
 import { resolve, join } from "node:path";
+import { fireOnError, type OnErrorHook } from "./lifecycle.ts";
 
 export interface I18nConfig {
   locales: string[];
@@ -38,6 +40,27 @@ export interface BractJSConfig {
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are intentional control flow and are NOT reported here. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
+  /**
+   * Pre-scanned route list (typically exported from `app/_generated/routes.ts`).
+   * When provided, skips the startup `Bun.Glob` scan of `appDir`. Required for
+   * `bun build --compile` binaries where the embedded filesystem has no
+   * scannable routes/ directory.
+   */
+  routeFiles?: RouteFile[];
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Required alongside `routeFiles` for compiled binaries — `resolveRouteChain`
+   * uses this map instead of `import(absPath)` at request time.
+   */
+  moduleRegistry?: ModuleRegistry;
+  /**
+   * Pre-imported server-action modules (typically `app/_generated/actions.ts`).
+   * When provided, skips the startup `Bun.Glob` scan + dynamic import that
+   * `loadServerActions` does.
+   */
+  actionModules?: Array<{ relPath: string; mod: Record<string, unknown> }>;
 }
 
 const DEFAULT_MANIFEST: ServerManifest = {
@@ -84,8 +107,18 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
       }))
     : Promise.resolve(config.manifest ?? DEFAULT_MANIFEST);
 
-  const trieReady = scanRoutes(appDir).then(buildTrie);
-  const actionsReady = loadServerActions(appDir);
+  // Codegen / compiled-binary path: when the caller supplies pre-scanned
+  // routes, skip the runtime `Bun.Glob` scan that `bun build --compile`
+  // can't satisfy (the routes/ directory isn't on the filesystem in a
+  // single-binary deployment). Same idea for server actions.
+  const trieReady = config.routeFiles
+    ? Promise.resolve(buildTrie(config.routeFiles))
+    : scanRoutes(appDir).then(buildTrie);
+  const actionsReady = config.actionModules
+    ? loadServerActionsFromRegistry(config.actionModules)
+    : loadServerActions(appDir);
+  const moduleRegistry = config.moduleRegistry;
+  const onError = config.onError;
 
   return async function fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
@@ -154,7 +187,7 @@ export function buildFetchHandler(config: Partial<BractJSConfig>) {
 
     const trie = await trieReady;
     const manifest = isDevRuntime() ? await readDevManifest(buildDir) : await manifestReady;
-    const handlerConfig: HandlerConfig = { appDir, publicDir, manifest };
+    const handlerConfig: HandlerConfig = { appDir, publicDir, manifest, onError, moduleRegistry };
     return handleRequest(request, trie, handlerConfig);
   };
 }
@@ -186,6 +219,7 @@ async function warnIfStaleBuild(buildDir: string): Promise<void> {
 let signalsRegistered = false;
 let isShuttingDown = false;
 let activeOnShutdown: (() => Promise<void> | void) | undefined;
+let activeOnError: OnErrorHook | undefined;
 
 export function createServer(config?: Partial<BractJSConfig>): {
   stop(): void;
@@ -213,6 +247,7 @@ export function createServer(config?: Partial<BractJSConfig>): {
   }
 
   activeOnShutdown = config?.onShutdown;
+  activeOnError = config?.onError;
 
   console.log(`[bract] Server running at http://localhost:${port}`);
 
@@ -224,37 +259,46 @@ export function createServer(config?: Partial<BractJSConfig>): {
     }
   };
 
-  const gracefulShutdown = (signal?: string) => {
+  // Programmatic / beforeExit path — runs the user hook, stops the adapter,
+  // and returns. Does NOT call process.exit() so callers (tests, parent
+  // supervisors) can keep running. `gracefulShutdown` below wraps this and
+  // adds an explicit exit for signal handlers, where termination is the
+  // whole point.
+  const shutdownOnce = async (signal?: string): Promise<void> => {
     if (isShuttingDown) return;
     isShuttingDown = true;
     if (signal) console.log(`\n[bract] Received ${signal}, shutting down…`);
     try {
       const result = activeOnShutdown?.();
       if (result instanceof Promise) {
-        result.catch((err) => console.error("[bract] onShutdown error:", err)).finally(() => {
-          stopAdapter();
-          process.exit(0);
-        });
-      } else {
-        stopAdapter();
-        process.exit(0);
+        try { await result; }
+        catch (err) { console.error("[bract] onShutdown error:", err); }
       }
     } catch (err) {
       console.error("[bract] onShutdown error:", err);
+    } finally {
       stopAdapter();
-      process.exit(1);
     }
   };
 
+  const gracefulShutdown = (signal?: string, exitCode = 0): void => {
+    void shutdownOnce(signal).finally(() => process.exit(exitCode));
+  };
+
   if (!signalsRegistered) {
     signalsRegistered = true;
     process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));
     process.on("SIGINT",  () => gracefulShutdown("SIGINT"));
     process.on("SIGUSR2", () => gracefulShutdown("SIGUSR2"));
-    process.on("beforeExit", () => gracefulShutdown());
+    // `beforeExit` fires when the event loop is naturally draining — we
+    // already shut down the adapter at that point, but we must NOT call
+    // process.exit(). Doing so re-enters the lifecycle and prevents test
+    // runners (and any parent process supervising us) from observing a
+    // clean exit code. Just run the user hook + stop the listener.
+    process.on("beforeExit", () => { void shutdownOnce(); });
     process.on("uncaughtException", (err) => {
       console.error("[bract] Uncaught exception:", err);
-      gracefulShutdown("uncaughtException");
+      void fireOnError(activeOnError, err).then(() => gracefulShutdown("uncaughtException", 1));
     });
   }
 
@@ -263,7 +307,12 @@ export function createServer(config?: Partial<BractJSConfig>): {
   });
 
   return {
-    stop() { void gracefulShutdown(); },
+    // Programmatic stop — runs `onShutdown`, then closes the listener. Does
+    // NOT call `process.exit()`. Tests rely on this so the runner can print
+    // its summary; long-running supervisors rely on it so a stop() doesn't
+    // tear down the whole worker. Use SIGTERM/SIGINT if you actually want
+    // the process to exit.
+    stop() { void shutdownOnce(); },
   };
 }
 

package/src/server/static.ts

@@ -4,20 +4,40 @@ import { realpath } from "node:fs/promises";
 const IMMUTABLE = "public, max-age=31536000, immutable";
 const NO_CACHE = "no-cache";
 
-// Resolve to a canonical path that follows symlinks. Returns null if the
-// target doesn't exist OR escapes the given root after symlink expansion.
+/**
+ * Resolve to a canonical path that follows symlinks, with a fallback for
+ * `bun build --compile` binaries.
+ *
+ * Three outcomes:
+ * 1. realpath succeeds + stays inside `root` → return resolved path
+ * 2. realpath throws AND `Bun.file(candidate)` exists → return the candidate
+ *    path. This is the embedded-asset case: `bun --compile` exposes assets
+ *    through virtual paths that don't appear in the filesystem, so realpath
+ *    errors with ENOENT/EINVAL but `Bun.file()` still reads them.
+ * 3. otherwise → null (escape, ENOENT, etc.)
+ *
+ * The structural `startsWith(root + sep)` check at the top runs before any
+ * I/O and is the authoritative traversal guard — the realpath check is
+ * defense-in-depth against symlink escape, which can't happen inside an
+ * embedded virtual filesystem.
+ */
 async function safeRealpath(root: string, requested: string): Promise<string | null> {
   const candidate = resolve(join(root, requested));
-  // Cheap structural reject before touching the FS.
+  // Cheap structural reject before touching the FS. This blocks `..` escapes
+  // unconditionally, in both the normal-FS and embedded-binary paths.
   if (!candidate.startsWith(root + sep) && candidate !== root) return null;
-  let real: string;
   try {
-    real = await realpath(candidate);
+    const real = await realpath(candidate);
+    if (!real.startsWith(root + sep) && real !== root) return null;
+    return real;
   } catch {
+    // realpath fails for paths embedded by `bun build --compile --asset`.
+    // The structural check above already prevented traversal, so the only
+    // remaining concern is whether the asset actually exists — defer to
+    // Bun.file() which reads from the embed table.
+    if (await Bun.file(candidate).exists()) return candidate;
     return null;
   }
-  if (!real.startsWith(root + sep) && real !== root) return null;
-  return real;
 }
 
 /**

package/templates/new-app/app/server.ts

@@ -0,0 +1,30 @@
+// Entry point for `bun build --compile`.
+//
+// Pre-generated registries below come from `bractjs codegen:registry` and
+// `bractjs codegen:manifest`. They turn every runtime fs scan / dynamic
+// import the framework would normally do into static, traceable imports so
+// `bun build --compile` can produce a single executable.
+//
+// Generate-then-compile:
+//   bractjs codegen:registry             # writes routes.ts + actions.ts
+//   bractjs build                        # writes build/client/* + manifest
+//   bractjs codegen:manifest             # snapshots manifest into TS
+//   bun build --compile app/server.ts --outfile myapp [--asset build/client/]
+//
+// Or run all of the above in one shot:
+//   bractjs compile
+
+import { createServer } from "@bractjs/bractjs";
+import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
+import { actionModules } from "./_generated/actions.ts";
+import { manifest } from "./_generated/manifest.ts";
+
+createServer({
+  port: Number(process.env.PORT ?? 3000),
+  appDir: "./app",
+  publicDir: "./public",
+  manifest,
+  routeFiles,
+  moduleRegistry,
+  actionModules,
+});

package/templates/new-app/package.json

@@ -5,7 +5,8 @@
   "scripts": {
     "dev": "bractjs dev",
     "build": "NODE_ENV=production bractjs build",
-    "start": "NODE_ENV=production bractjs start"
+    "start": "NODE_ENV=production bractjs start",
+    "compile": "NODE_ENV=production bractjs compile"
   },
   "dependencies": {
     "@bractjs/bractjs": "latest",

package/types/config.d.ts

@@ -1,4 +1,5 @@
 import type { BunPlugin } from "bun";
+import type { RouteFile, RouteModule } from "./route.d.ts";
 
 export interface BractJSConfig {
   /** TCP port to listen on. Default: 3000. */
@@ -23,6 +24,23 @@ export interface BractJSConfig {
   onStart?: () => Promise<void> | void;
   /** Called before the process exits (any signal or uncaught error). Use to close DB connections, flush queues, etc. */
   onShutdown?: () => Promise<void> | void;
+  /**
+   * Pre-scanned route list. Typically imported from `app/_generated/routes.ts`.
+   * Required for `bun build --compile` binaries where the routes/ directory
+   * isn't on a scannable filesystem.
+   */
+  routeFiles?: RouteFile[];
+  /**
+   * Pre-loaded route/layout/root modules keyed by appDir-relative path.
+   * Typically imported from `app/_generated/routes.ts`.
+   */
+  moduleRegistry?: Record<string, RouteModule | Record<string, unknown>>;
+  /**
+   * Pre-imported server-action modules. Typically imported from
+   * `app/_generated/actions.ts`. Each `relPath` MUST match what the client
+   * proxy plugin hashed during the client build.
+   */
+  actionModules?: Array<{ relPath: string; mod: Record<string, unknown> }>;
 }
 
 export interface ServerManifest {
@@ -31,3 +49,13 @@ export interface ServerManifest {
   /** Map of URL pattern → route asset info. */
   routes: Record<string, { file?: string; chunk?: string }>;
 }
+
+/** Subset of BractJSConfig used by the build pipeline. All fields optional. */
+export interface BuildConfig {
+  appDir?: string;
+  buildDir?: string;
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  minify?: boolean;
+  clientEnv?: string[];
+  plugins?: import("bun").BunPlugin[];
+}

package/types/index.d.ts

@@ -4,10 +4,11 @@ import type { ReactNode, Context } from "react";
 export type {
   LoaderArgs, ActionArgs, MetaDescriptor, MetaArgs,
   LoaderFunction, ActionFunction, MetaFunction, RouteModule,
+  RouteFile, Segment,
 } from "./route.d.ts";
 
 // ── Config + Server ───────────────────────────────────────────────────────
-export type { BractJSConfig, ServerManifest } from "./config.d.ts";
+export type { BractJSConfig, ServerManifest, BuildConfig } from "./config.d.ts";
 import type { MetaDescriptor } from "./route.d.ts";
 import type { BractJSConfig, ServerManifest } from "./config.d.ts";
 
@@ -22,9 +23,13 @@ export interface RenderOptions {
   status?: number;
 }
 
+export type OnErrorHook = (err: unknown, request?: Request) => Promise<void> | void;
+
 export interface LifecycleHooks {
   onStart?: () => Promise<void> | void;
   onShutdown?: () => Promise<void> | void;
+  /** Called for every unexpected error: loader failures, action throws, and uncaught process exceptions. Redirects and HttpErrors are NOT reported here. The request is undefined for process-level exceptions. */
+  onError?: OnErrorHook;
 }
 export declare function defineLifecycle(hooks: LifecycleHooks): LifecycleHooks;
 export declare function createServer(config?: Partial<BractJSConfig>): { stop(): void };
@@ -203,5 +208,49 @@ export declare function makeCloudflareHandler(
 export declare const cssModulesPlugin: unknown; // BunPlugin
 export declare function transformCssModule(filePath: string): Promise<{ map: Record<string, string>; css: string }>;
 
+// ── Build plugins (required for native `bun build --compile` workflow) ───
+//
+// Apply all of these on the relevant bundle or face crashes / secret leaks:
+//   server bundle  → useClientStubPlugin
+//   client bundle  → createUseServerProxyPlugin(appDir), serverOnlyPlugin,
+//                    clientEnvPlugin(allowedKeys, env), cssModulesPlugin
+export declare const useClientStubPlugin: unknown; // BunPlugin
+export declare function createUseServerProxyPlugin(appDir?: string): unknown; // BunPlugin
+export declare const useServerProxyPlugin: unknown; // BunPlugin (legacy — uses absolute paths)
+export declare const serverOnlyPlugin: unknown; // BunPlugin
+export declare function clientEnvPlugin(
+  allowedKeys: string[],
+  envValues: Record<string, string>,
+): unknown; // BunPlugin
+
+// ── Module-registry codegen (drives `bun build --compile`) ────────────────
+export interface CodegenResult {
+  routesPath: string;
+  actionsPath: string;
+}
+/** Scan appDir; write `<appDir>/_generated/routes.ts` and `actions.ts`. */
+export declare function writeModuleRegistries(appDir: string): Promise<CodegenResult>;
+/** Read `<buildDir>/route-manifest.json`; write `<appDir>/_generated/manifest.ts`. */
+export declare function writeManifestModule(appDir: string, buildDir: string): Promise<string>;
+
+/** Pre-loaded route/layout/root modules keyed by appDir-relative path. */
+export type ModuleRegistry = Record<string, import("./route.d.ts").RouteModule | Record<string, unknown>>;
+
 // ── buildFetchHandler (D1) ───────────────────────────────────────────────
 export declare function buildFetchHandler(config: Partial<import("./config.d.ts").BractJSConfig>): (request: Request) => Promise<Response>;
+
+// ── Programmatic API ─────────────────────────────────────────────────────
+export declare function runBuild(config: import("./config.d.ts").BuildConfig): Promise<void>;
+
+export interface DevServerOptions {
+  port?: number;
+  hmrPort?: number;
+  config?: Partial<BractJSConfig>;
+  skipUserConfig?: boolean;
+}
+export interface DevServer {
+  stop(): void;
+}
+export declare function createDevServer(options?: DevServerOptions): Promise<DevServer>;
+
+export declare function loadUserConfig(): Promise<Partial<BractJSConfig>>;

package/types/route.d.ts

@@ -50,3 +50,11 @@ export interface RouteModule<TLoader = unknown, TAction = unknown> {
   ErrorBoundary?: ComponentType<{ error: unknown }>;
   default?: ComponentType;
 }
+
+export type Segment = string | { param: string } | { catchAll: string };
+
+export interface RouteFile {
+  filePath: string;
+  urlPattern: string;
+  segments: Segment[];
+}