@bractjs/bractjs 0.1.0

package/src/dev/rebuilder.ts

@@ -0,0 +1,95 @@
+import type { BractJSConfig } from "../server/serve.ts";
+import { useServerProxyPlugin } from "../build/directives.ts";
+import { scanRoutes } from "../server/scanner.ts";
+import { generateManifest, writeManifest } from "../build/manifest.ts";
+import { mkdir, rename, rm } from "node:fs/promises";
+import { join, resolve, basename, extname } from "node:path";
+
+// Shim filename written inside the demo app's CWD during build (then deleted).
+// The framework's entry.tsx lives outside CWD. When Bun sees entrypoints outside
+// CWD it picks a common-ancestor project root, placing the entry at a nested
+// virtual path and generating ../ traversals in chunk imports. Those traversals
+// produce wrong URLs after we rename entry.js → client.js. A shim inside CWD
+// keeps all entrypoints under one root so chunk refs stay flat and correct.
+const SHIM = ".bractjs-entry.tsx";
+
+export async function rebuildClient(
+  config?: Partial<BractJSConfig>,
+): Promise<{ duration: number }> {
+  const start = Date.now();
+  const appDir = config?.appDir ?? "./app";
+  const pkgRoot = resolve(import.meta.dirname, "../..");
+  const outdir = resolve(process.cwd(), config?.buildDir ?? "build", "client");
+  const buildDir = resolve(process.cwd(), config?.buildDir ?? "build");
+  const entrypoint = resolve(pkgRoot, "src/client/entry.tsx");
+
+  // Clean output dir so stale artifacts from previous builds can't be served.
+  await rm(outdir, { recursive: true, force: true });
+  await mkdir(outdir, { recursive: true });
+
+  const routes = await scanRoutes(appDir);
+  const routePaths = routes.map((r) => resolve(process.cwd(), appDir, r.filePath));
+  const rootPath = resolve(process.cwd(), appDir, "root.tsx");
+  const appDirClean = appDir.replace(/^\.\//, ""); // "./app" → "app"
+
+  // Write shim, build, always delete shim.
+  const shimPath = resolve(process.cwd(), SHIM);
+  await Bun.write(shimPath, `import "${entrypoint}";\nexport {};\n`);
+
+  let result: Awaited<ReturnType<typeof Bun.build>>;
+  try {
+    result = await Bun.build({
+      entrypoints: [shimPath, rootPath, ...routePaths],
+      target: "browser",
+      splitting: true, // shared React chunk prevents dual-React / invalid hook call
+      outdir,
+      // No publicPath: relative refs resolve correctly because static.ts serves
+      // /build/client/ directly from outdir, so the URL structure matches the file
+      // structure. publicPath + ../ traversals produce wrong absolute URLs.
+      minify: false,
+      sourcemap: "inline",
+      plugins: [useServerProxyPlugin],
+    });
+  } finally {
+    await rm(shimPath, { force: true });
+  }
+
+  if (!result.success) {
+    for (const log of result.logs) console.error("[bractjs] build error:", log);
+    return { duration: Date.now() - start };
+  }
+
+  const routeChunks = new Map<string, string>();
+  const clientEntry = "/build/client/client.js";
+  const shimBase = basename(SHIM, extname(SHIM)); // ".bractjs-entry"
+  let rootChunk: string | undefined;
+
+  for (const output of result.outputs) {
+    if (output.kind !== "entry-point") continue;
+    const outBase = basename(output.path, extname(output.path));
+    // rel: path of this output relative to outdir, e.g. "app/routes/_index.js"
+    const rel = output.path.slice(outdir.length + 1);
+
+    if (outBase === shimBase) {
+      // Rename shim output → client.js
+      const target = join(outdir, "client.js");
+      if (output.path !== target) await rename(output.path, target);
+    } else if (rel === join(appDirClean, "root.js")) {
+      // Root component chunk — the shell that wraps <Outlet />
+      rootChunk = "/build/client/" + rel;
+    } else {
+      // Match by full relative path to avoid basename collisions (_index appears N times).
+      // Input: appDirClean/r.filePath. Output mirrors that structure under outdir.
+      const matched = routes.find((r) => {
+        const expected = join(appDirClean, r.filePath).replace(/\.[^.]+$/, ".js");
+        return rel === expected;
+      });
+      if (matched) {
+        routeChunks.set(matched.urlPattern, "/build/client/" + rel);
+      }
+    }
+  }
+
+  await writeManifest(generateManifest({ clientEntry, rootChunk, routeChunks }), buildDir);
+  return { duration: Date.now() - start };
+}

package/src/dev/server.ts

@@ -0,0 +1,38 @@
+import { createServer } from "../server/serve.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";
+
+const hmr = createHmrServer(3001);
+
+// Build client bundle before the HTTP server starts accepting requests
+const { duration: initialMs } = await rebuildClient();
+console.log(`[bractjs] initial client build in ${initialMs}ms`);
+
+createServer({ port: 3000 });
+
+watchApp("./app", async (file) => {
+  const { duration } = await rebuildClient();
+
+  // Route files (not layout): do a fine-grained module swap without full reload.
+  // Root, layouts, and other files: fall back to full page reload.
+  const isRoute =
+    file.startsWith("routes/") &&
+    !file.endsWith("layout.tsx") &&
+    !file.endsWith("layout.ts");
+
+  if (isRoute) {
+    const pattern = filePathToPattern(file);
+    // Chunk URL = same basename as route file; splitting build puts it in build/client/
+    const chunkUrl = `/build/client/${basename(file, extname(file))}.js`;
+    hmr.broadcast({ type: "hmr:route", pattern, chunkUrl, file, duration });
+    console.log(`✓ ${file} → module swap (pattern="${pattern}") in ${duration}ms`);
+  } else {
+    hmr.broadcast({ type: "hmr:reload", file, duration });
+    console.log(`✓ ${file} → full reload in ${duration}ms`);
+  }
+});
+
+console.log("BractJS dev server on http://localhost:3000");

package/src/dev/watcher.ts

@@ -0,0 +1,32 @@
+import path from "node:path";
+import { watch } from "node:fs";
+
+const WATCHED_EXTENSIONS = new Set([".tsx", ".ts", ".css"]);
+
+/**
+ * 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 {
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  let pendingFile = "";
+
+  watch(appDir, { recursive: true }, (_eventType, filename) => {
+    if (!filename) return;
+
+    const ext = path.extname(filename);
+    if (!WATCHED_EXTENSIONS.has(ext)) return;
+
+    pendingFile = filename;
+
+    if (debounceTimer !== null) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = null;
+      console.log(`✓ ${path.basename(pendingFile)} changed`);
+      onChange(pendingFile);
+    }, 50);
+  });
+}

package/src/image/cache.ts

@@ -0,0 +1,75 @@
+import { join } from "node:path";
+import { mkdir } from "node:fs/promises";
+import type { ImageTransformParams, TransformResult, ImageFormat } from "./types.ts";
+
+const MAX_MEM = 200;
+const mem = new Map<string, { result: TransformResult; hits: number }>();
+
+async function cacheKey(src: string, params: ImageTransformParams): Promise<string> {
+  const raw = new TextEncoder().encode(JSON.stringify({ src, ...params }));
+  const hash = await crypto.subtle.digest("SHA-256", raw);
+  return Array.from(new Uint8Array(hash))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 16);
+}
+
+export async function getFromMemory(
+  src: string,
+  params: ImageTransformParams,
+): Promise<TransformResult | null> {
+  const key = await cacheKey(src, params);
+  const entry = mem.get(key);
+  if (!entry) return null;
+  entry.hits++;
+  return entry.result;
+}
+
+export async function setInMemory(
+  src: string,
+  params: ImageTransformParams,
+  result: TransformResult,
+): Promise<void> {
+  const key = await cacheKey(src, params);
+  if (mem.size >= MAX_MEM) {
+    let minKey = "";
+    let minHits = Infinity;
+    for (const [k, v] of mem) {
+      if (v.hits < minHits) { minHits = v.hits; minKey = k; }
+    }
+    if (minKey) mem.delete(minKey);
+  }
+  mem.set(key, { result, hits: 0 });
+}
+
+export async function getFromDisk(
+  dir: string,
+  src: string,
+  params: ImageTransformParams,
+): Promise<TransformResult | null> {
+  const key = await cacheKey(src, params);
+  const metaFile = Bun.file(join(dir, `${key}.json`));
+  const dataFile = Bun.file(join(dir, `${key}.bin`));
+  if (!(await metaFile.exists()) || !(await dataFile.exists())) return null;
+  try {
+    const meta = await metaFile.json() as { contentType: string; format: ImageFormat };
+    const data = await dataFile.arrayBuffer();
+    return { data, contentType: meta.contentType, format: meta.format };
+  } catch {
+    return null;
+  }
+}
+
+export async function setOnDisk(
+  dir: string,
+  src: string,
+  params: ImageTransformParams,
+  result: TransformResult,
+): Promise<void> {
+  await mkdir(dir, { recursive: true });
+  const key = await cacheKey(src, params);
+  await Promise.all([
+    Bun.write(join(dir, `${key}.json`), JSON.stringify({ contentType: result.contentType, format: result.format })),
+    Bun.write(join(dir, `${key}.bin`), result.data),
+  ]);
+}

package/src/image/handler.ts

@@ -0,0 +1,82 @@
+import { join, resolve } from "node:path";
+import type { ImageTransformParams, ImageFormat, ImageFit } from "./types.ts";
+import { QUALITY_DEFAULT, FORMAT_DEFAULT, FIT_DEFAULT, MIME } from "./types.ts";
+import { transformImage } from "./optimizer.ts";
+import { getFromMemory, setInMemory, getFromDisk, setOnDisk } from "./cache.ts";
+
+const MAX_DIM = 4096;
+const CACHE_CTRL = "public, max-age=31536000, immutable";
+
+function parseParams(
+  sp: URLSearchParams,
+  publicDir: string,
+): { 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;
+
+  const rel = src.slice("/public/".length);
+  const root = resolve(publicDir);
+  const filePath = resolve(join(root, rel));
+  if (!filePath.startsWith(root + "/") && filePath !== root) return null;
+
+  const wRaw = sp.get("w");
+  const hRaw = sp.get("h");
+  const w = wRaw ? parseInt(wRaw, 10) : undefined;
+  const h = hRaw ? parseInt(hRaw, 10) : undefined;
+  if (w !== undefined && (isNaN(w) || w < 1 || w > MAX_DIM)) return null;
+  if (h !== undefined && (isNaN(h) || h < 1 || h > MAX_DIM)) return null;
+
+  const q = Math.min(100, Math.max(1, parseInt(sp.get("q") ?? String(QUALITY_DEFAULT), 10)));
+  const fmt = (sp.get("format") ?? FORMAT_DEFAULT) as ImageFormat;
+  const fit = (sp.get("fit") ?? FIT_DEFAULT) as ImageFit;
+  if (!MIME[fmt]) return null;
+
+  return { src, filePath, params: { w, h, q, format: fmt, fit } };
+}
+
+function imageResponse(result: { data: ArrayBuffer; contentType: string }, cacheStatus: string): Response {
+  return new Response(result.data, {
+    headers: {
+      "Content-Type": result.contentType,
+      "Cache-Control": CACHE_CTRL,
+      "X-Image-Cache": cacheStatus,
+    },
+  });
+}
+
+export async function handleImageRequest(
+  request: Request,
+  publicDir: string,
+  cacheDir: string,
+): Promise<Response | null> {
+  const url = new URL(request.url);
+  if (url.pathname !== "/_image") return null;
+
+  const parsed = parseParams(url.searchParams, publicDir);
+  if (!parsed) return new Response("Bad Request", { status: 400 });
+
+  const { src, filePath, params } = parsed;
+  if (!(await Bun.file(filePath).exists())) {
+    return new Response("Not Found", { status: 404 });
+  }
+
+  const memHit = await getFromMemory(src, params);
+  if (memHit) return imageResponse(memHit, "MEM");
+
+  const diskHit = await getFromDisk(cacheDir, src, params);
+  if (diskHit) {
+    setInMemory(src, params, diskHit).catch(() => {});
+    return imageResponse(diskHit, "DISK");
+  }
+
+  try {
+    const result = await transformImage(filePath, params);
+    setInMemory(src, params, result).catch(() => {});
+    setOnDisk(cacheDir, src, params, result).catch(() => {});
+    return imageResponse(result, "MISS");
+  } catch (err) {
+    console.error("[bractjs] image optimization error:", err);
+    return new Response("Internal Server Error", { status: 500 });
+  }
+}

package/src/image/optimizer.ts

@@ -0,0 +1,76 @@
+import type { ImageTransformParams, TransformResult, ImageFormat } from "./types.ts";
+import { MIME } from "./types.ts";
+
+// Probe for an available ImageMagick binary once, then cache the result.
+let _binary: string | null | undefined;
+
+async function detectBinary(): Promise<string | null> {
+  for (const bin of ["magick", "convert"]) {
+    try {
+      const proc = Bun.spawn([bin, "-version"], { stdout: "ignore", stderr: "ignore" });
+      if ((await proc.exited) === 0) return bin;
+    } catch { /* not found */ }
+  }
+  return null;
+}
+
+async function getBinary(): Promise<string | null> {
+  if (_binary !== undefined) return _binary;
+  _binary = await detectBinary();
+  return _binary;
+}
+
+function resizeArgs(params: ImageTransformParams): string[] {
+  if (!params.w && !params.h) return [];
+  const dim = `${params.w ?? ""}x${params.h ?? ""}`;
+  if (params.fit === "fill") return ["-resize", `${dim}!`];
+  if (params.fit === "contain") return ["-resize", dim];
+  // cover: scale to fill then crop to exact box
+  const args = ["-resize", `${dim}^`];
+  if (params.w && params.h) args.push("-gravity", "Center", "-extent", dim);
+  return args;
+}
+
+function buildArgs(binary: string, input: string, params: ImageTransformParams): string[] {
+  const base = binary === "magick" ? ["magick", "convert"] : ["convert"];
+  return [
+    ...base,
+    input,
+    ...resizeArgs(params),
+    "-quality", String(params.q),
+    "-strip",
+    `${params.format}:-`,
+  ];
+}
+
+export async function transformImage(
+  filePath: string,
+  params: ImageTransformParams,
+): Promise<TransformResult> {
+  const binary = await getBinary();
+
+  // No ImageMagick available — serve the original file as-is.
+  if (!binary) {
+    const data = await Bun.file(filePath).arrayBuffer();
+    const ext = filePath.split(".").pop()?.toLowerCase() ?? "jpeg";
+    const fmt = (ext === "jpg" ? "jpeg" : ext) as ImageFormat;
+    return { data, contentType: MIME[fmt] ?? "image/jpeg", format: fmt };
+  }
+
+  const proc = Bun.spawn(buildArgs(binary, filePath, params), {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const [data, , exitCode] = await Promise.all([
+    new Response(proc.stdout!).arrayBuffer(),
+    new Response(proc.stderr!).arrayBuffer(),
+    proc.exited,
+  ]);
+
+  if (exitCode !== 0) {
+    throw new Error(`[bractjs] ImageMagick exited ${exitCode} for ${filePath}`);
+  }
+
+  return { data, contentType: MIME[params.format], format: params.format };
+}

package/src/image/types.ts

@@ -0,0 +1,27 @@
+export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
+export type ImageFit = "cover" | "contain" | "fill";
+
+export interface ImageTransformParams {
+  w?: number;
+  h?: number;
+  q: number;
+  format: ImageFormat;
+  fit: ImageFit;
+}
+
+export interface TransformResult {
+  data: ArrayBuffer;
+  contentType: string;
+  format: ImageFormat;
+}
+
+export const QUALITY_DEFAULT = 80;
+export const FORMAT_DEFAULT: ImageFormat = "webp";
+export const FIT_DEFAULT: ImageFit = "cover";
+export const BREAKPOINTS = [320, 640, 768, 1024, 1280, 1536, 1920];
+export const MIME: Record<ImageFormat, string> = {
+  webp: "image/webp",
+  avif: "image/avif",
+  jpeg: "image/jpeg",
+  png:  "image/png",
+};

package/src/index.ts

@@ -0,0 +1,51 @@
+// Server
+export { createServer, renderRoute, redirect, json, error } from "./server/index.ts";
+export type { BractJSConfig, RenderOptions, ServerManifest } from "./server/index.ts";
+
+// Shared types
+export type {
+  LoaderArgs,
+  ActionArgs,
+  MetaDescriptor,
+  MetaArgs,
+  LoaderFunction,
+  ActionFunction,
+  MetaFunction,
+  RouteModule,
+  RouteDefinition,
+} from "./shared/route-types.ts";
+
+export { BractJSError, HttpError, isRedirect, isHttpError, isBractJSError } from "./shared/errors.ts";
+export { Deferred, defer, isDeferred } from "./shared/deferred.ts";
+export { BractJSContext, BractJSProvider, useBractJSContext } from "./shared/context.ts";
+export type { BractJSContextValue, RouteManifest } from "./shared/context.ts";
+
+// Middleware
+export { pipeline, MiddlewarePipeline } from "./server/middleware.ts";
+export type { MiddlewareFn, MiddlewareContext } from "./server/middleware.ts";
+export { requestLogger } from "./middleware/requestLogger.ts";
+export { cors } from "./middleware/cors.ts";
+export type { CorsOptions } from "./middleware/cors.ts";
+export { authGuard } from "./middleware/authGuard.ts";
+export type { AuthGuardOptions, SessionStorageLike, SessionLike } from "./middleware/authGuard.ts";
+
+// Session
+export { createCookieSession } from "./server/session.ts";
+export type { Session, SessionStorage, SessionData, CookieSessionOptions, CommitOptions } from "./server/session.ts";
+
+// Client components
+export { Scripts } from "./client/components/Scripts.tsx";
+export { LiveReload } from "./client/components/LiveReload.tsx";
+export { Outlet } from "./client/components/Outlet.tsx";
+export { Link } from "./client/components/Link.tsx";
+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";
+
+// Client hooks
+export { useLoaderData } from "./client/hooks/useLoaderData.ts";
+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";

package/src/middleware/authGuard.ts

@@ -0,0 +1,37 @@
+import type { MiddlewareFn } from "../server/middleware.ts";
+
+/** Minimal session interface — will be unified with createCookieSession in 5.3. */
+export interface SessionLike {
+  get(key: string): unknown;
+}
+
+export interface SessionStorageLike {
+  getSession(cookie?: string | null): Promise<SessionLike>;
+}
+
+export interface AuthGuardOptions {
+  session: SessionStorageLike;
+  required?: boolean;
+}
+
+/**
+ * Reads the Cookie header → gets session → sets ctx.context.user.
+ * If required=true and no user, returns 401.
+ */
+export function authGuard(options: AuthGuardOptions): MiddlewareFn {
+  return async (ctx, next) => {
+    const cookie = ctx.request.headers.get("Cookie");
+    const session = await options.session.getSession(cookie);
+    const user = session.get("user");
+    ctx.context.user = user ?? null;
+
+    if (options.required && !user) {
+      return new Response(JSON.stringify({ error: "Unauthorized" }), {
+        status: 401,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    return next();
+  };
+}

package/src/middleware/cors.ts

@@ -0,0 +1,36 @@
+import type { MiddlewareFn } from "../server/middleware.ts";
+
+export interface CorsOptions {
+  origin: string | string[];
+  methods?: string[];
+}
+
+/**
+ * Sets CORS headers. Handles OPTIONS preflight with 204.
+ */
+export function cors(options: CorsOptions): MiddlewareFn {
+  const allowedOrigins = Array.isArray(options.origin)
+    ? options.origin
+    : [options.origin];
+  const allowedMethods = options.methods?.join(", ") ?? "GET, POST, PUT, DELETE, PATCH, OPTIONS";
+
+  return async (ctx, next) => {
+    const origin = ctx.request.headers.get("Origin") ?? "";
+    const allowed = allowedOrigins.includes("*") || allowedOrigins.includes(origin);
+    const corsHeaders: Record<string, string> = {
+      "Access-Control-Allow-Methods": allowedMethods,
+      "Access-Control-Allow-Headers": "Content-Type, Authorization",
+    };
+    if (allowed) corsHeaders["Access-Control-Allow-Origin"] = origin || "*";
+
+    // Preflight
+    if (ctx.request.method === "OPTIONS") {
+      return new Response(null, { status: 204, headers: corsHeaders });
+    }
+
+    const response = await next();
+    const patched = new Response(response.body, response);
+    for (const [k, v] of Object.entries(corsHeaders)) patched.headers.set(k, v);
+    return patched;
+  };
+}

package/src/middleware/requestLogger.ts

@@ -0,0 +1,15 @@
+import type { MiddlewareFn } from "../server/middleware.ts";
+
+/**
+ * Logs "[METHOD] /path → status in Xms" for every request.
+ */
+export function requestLogger(): MiddlewareFn {
+  return async (ctx, next) => {
+    const start = Date.now();
+    const { pathname } = new URL(ctx.request.url);
+    const response = await next();
+    const ms = Date.now() - start;
+    console.log(`[${ctx.request.method}] ${pathname} → ${response.status} in ${ms}ms`);
+    return response;
+  };
+}

package/src/server/action-handler.ts

@@ -0,0 +1,35 @@
+import { resolveAction } from "./action-registry.ts";
+import { json } from "./response.ts";
+
+export async function handleActionRequest(request: Request): Promise<Response | null> {
+  const url = new URL(request.url);
+  if (!url.pathname.startsWith("/_action")) return null;
+  if (request.method !== "POST") return new Response("Method Not Allowed", { status: 405 });
+
+  const id = url.searchParams.get("id");
+  if (!id) return new Response("Bad Request: missing action id", { status: 400 });
+
+  const fn = resolveAction(id);
+  if (!fn) return new Response("Not Found", { status: 404 });
+
+  let args: unknown[];
+  try {
+    const ct = request.headers.get("Content-Type") ?? "";
+    if (ct.includes("multipart/form-data") || ct.includes("application/x-www-form-urlencoded")) {
+      args = [await request.formData()];
+    } else {
+      const text = await request.text();
+      args = text ? JSON.parse(text) as unknown[] : [];
+    }
+  } catch {
+    return new Response("Bad Request: invalid body", { status: 400 });
+  }
+
+  try {
+    const result = await fn(...args);
+    return json(result ?? null);
+  } catch (err) {
+    console.error("[bractjs] server action error:", err);
+    return new Response("Internal Server Error", { status: 500 });
+  }
+}

package/src/server/action-registry.ts

@@ -0,0 +1,41 @@
+import { join } from "node:path";
+
+const SERVER_RE = /^["']use server["']/m;
+const registry = new Map<string, (...args: unknown[]) => Promise<unknown>>();
+
+async function computeId(filePath: string, name: string): Promise<string> {
+  const raw = new TextEncoder().encode(filePath + "#" + name);
+  const buf = await crypto.subtle.digest("SHA-256", raw);
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+    .slice(0, 16);
+}
+
+export function resolveAction(id: string): ((...args: unknown[]) => Promise<unknown>) | null {
+  return registry.get(id) ?? null;
+}
+
+export async function loadServerActions(appDir: string): Promise<void> {
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  for await (const rel of glob.scan(appDir)) {
+    const filePath = join(appDir, rel);
+    let src: string;
+    try { src = await Bun.file(filePath).text(); } catch { continue; }
+    if (!SERVER_RE.test(src)) continue;
+
+    let mod: Record<string, unknown>;
+    try {
+      mod = await import(filePath) as Record<string, unknown>;
+    } catch (err) {
+      console.error("[bractjs] failed to load server actions from", rel, err);
+      continue;
+    }
+
+    for (const [name, val] of Object.entries(mod)) {
+      if (typeof val !== "function") continue;
+      const id = await computeId(filePath, name);
+      registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
+    }
+  }
+}

package/src/server/env.ts

@@ -0,0 +1,29 @@
+export function isDev(): boolean {
+  return Bun.env.NODE_ENV !== "production";
+}
+
+export function requireEnv(key: string): string {
+  const value = Bun.env[key];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${key}`);
+  }
+  return value;
+}
+
+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);
+    }
+    return value;
+  });
+  // Escape HTML-sensitive characters so this JSON is safe to embed inside a
+  // <script> tag.  \u003c / \u003e / \u0026 are valid JSON unicode escapes —
+  // JSON.parse on the client decodes them transparently.
+  return json
+    .replace(/</g, "\\u003c")
+    .replace(/>/g, "\\u003e")
+    .replace(/&/g, "\\u0026");
+}