@bractjs/bractjs 0.1.0

package/src/server/scanner.ts

@@ -0,0 +1,68 @@
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export type Segment = string | { param: string } | { catchAll: string };
+
+export interface RouteFile {
+  filePath: string;
+  urlPattern: string;
+  segments: Segment[];
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+export function pathToSegments(pattern: string): Segment[] {
+  if (pattern === "") return [];
+  return pattern.split("/").map((seg) => {
+    if (seg.startsWith("[...") && seg.endsWith("]")) {
+      return { catchAll: seg.slice(4, -1) };
+    }
+    if (seg.startsWith("[") && seg.endsWith("]")) {
+      return { param: seg.slice(1, -1) };
+    }
+    return seg;
+  });
+}
+
+export function filePathToPattern(filePath: string): string {
+  // Strip "routes/" prefix and file extension
+  let path = filePath.replace(/^routes\//, "").replace(/\.(tsx|ts)$/, "");
+
+  // Handle nested _index (e.g. blog/_index → blog)
+  path = path.replace(/\/_index$/, "");
+
+  // Handle root _index
+  if (path === "_index" || path === "") return "";
+
+  // Convert [param] and [...catchAll] segments — keep as-is for pattern string
+  return path;
+}
+
+function segmentScore(seg: Segment): number {
+  if (typeof seg === "string") return 0;       // static
+  if ("param" in seg) return 1;                // dynamic
+  return 2;                                    // catch-all
+}
+
+function routeScore(route: RouteFile): number {
+  return route.segments.reduce((sum, seg) => sum + segmentScore(seg), 0);
+}
+
+// ── Main ───────────────────────────────────────────────────────────────────
+
+export async function scanRoutes(appDir: string): Promise<RouteFile[]> {
+  const glob = new Bun.Glob("routes/**/*.{tsx,ts}");
+  const routes: RouteFile[] = [];
+
+  for await (const filePath of glob.scan(appDir)) {
+    // Skip layout files — handled separately
+    if (filePath.endsWith("/layout.tsx") || filePath.endsWith("/layout.ts")) {
+      continue;
+    }
+
+    const urlPattern = filePathToPattern(filePath);
+    const segments = pathToSegments(urlPattern);
+    routes.push({ filePath, urlPattern, segments });
+  }
+
+  return routes.sort((a, b) => routeScore(a) - routeScore(b));
+}

package/src/server/serve.ts

@@ -0,0 +1,131 @@
+import { scanRoutes } from "./scanner.ts";
+import { buildTrie } from "./matcher.ts";
+import { handleRequest, type HandlerConfig } from "./request-handler.ts";
+import { type ServerManifest } from "./render.ts";
+import { isDev } 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 { handleActionRequest } from "./action-handler.ts";
+import { resolve, join } from "node:path";
+
+export interface BractJSConfig {
+  port: number;
+  appDir: string;
+  publicDir: string;
+  manifest: ServerManifest;
+  // Build options (used by src/build/bundler.ts)
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  minify?: boolean;
+  clientEnv?: string[];
+  buildDir?: string;
+  /** Directory for transformed image cache. Defaults to .bract-image-cache */
+  imageCacheDir?: string;
+}
+
+const DEFAULT_MANIFEST: ServerManifest = {
+  clientEntry: "/build/client/client.js",
+  routes: {},
+};
+
+/**
+ * In dev mode: read the manifest from disk on every request so that rebuilds
+ * are reflected immediately without restarting the server.
+ * The manifest is written by rebuildClient() in src/dev/rebuilder.ts.
+ */
+async function readDevManifest(buildDir: string): Promise<ServerManifest> {
+  const f = Bun.file(join(buildDir, "route-manifest.json"));
+  if (!(await f.exists())) return DEFAULT_MANIFEST;
+  const m = await f.json() as { clientEntry?: string; rootChunk?: string; routes?: Record<string, { chunk?: string }> };
+  return {
+    clientEntry: m.clientEntry ?? DEFAULT_MANIFEST.clientEntry,
+    rootChunk: m.rootChunk,
+    routes: Object.fromEntries(
+      Object.entries(m.routes ?? {}).map(([pat, e]) => [pat, { file: e.chunk ?? "", chunk: e.chunk }]),
+    ),
+  };
+}
+
+export function createServer(config?: Partial<BractJSConfig>): {
+  server: ReturnType<typeof Bun.serve>;
+  stop(): void;
+} {
+  const port = config?.port ?? 3000;
+  const appDir = resolve(config?.appDir ?? "./app");
+  const publicDir = resolve(config?.publicDir ?? "./public");
+  const buildDir = resolve(config?.buildDir ?? "./build");
+  const imageCacheDir = resolve(config?.imageCacheDir ?? ".bract-image-cache");
+
+  // In production, load the pre-built manifest; otherwise use provided or default
+  const manifestReady: Promise<ServerManifest> = !isDev() && !config?.manifest
+    ? loadManifest(buildDir).then((m) => ({
+        clientEntry: m.clientEntry,
+        rootChunk: m.rootChunk,
+        routes: Object.fromEntries(
+          Object.entries(m.routes).map(([pat, e]) => [pat, { file: e.chunk, chunk: e.chunk }]),
+        ),
+      }))
+    : Promise.resolve(config?.manifest ?? DEFAULT_MANIFEST);
+
+  // Build route trie and register server actions concurrently at startup.
+  const trieReady = scanRoutes(appDir).then(buildTrie);
+  const actionsReady = loadServerActions(appDir);
+
+  const server = Bun.serve({
+    port,
+    async fetch(request) {
+      const url = new URL(request.url);
+      const { pathname } = url;
+
+      // Dev-only: on-demand module compilation for HMR module swap
+      if (isDev() && pathname === "/_hmr/module") {
+        const { handleHmrModuleRequest } = await import("../dev/hmr-module-handler.ts");
+        return handleHmrModuleRequest(url, appDir);
+      }
+
+      // Server actions endpoint
+      if (pathname.startsWith("/_action")) {
+        await actionsReady;
+        const actionRes = await handleActionRequest(request);
+        if (actionRes) return actionRes;
+      }
+
+      // Image optimization endpoint
+      if (pathname === "/_image") {
+        const imgRes = await handleImageRequest(request, publicDir, imageCacheDir);
+        if (imgRes) return imgRes;
+      }
+
+      // Serve hashed client assets + public/ with correct cache headers
+      const staticRes = await serveStatic(pathname, buildDir, publicDir);
+      if (staticRes) return staticRes;
+
+      const trie = await trieReady;
+      const manifest = isDev() ? await readDevManifest(buildDir) : await manifestReady;
+      const handlerConfig: HandlerConfig = { appDir, publicDir, manifest };
+      return handleRequest(request, trie, handlerConfig);
+    },
+    // Return JSON for any uncaught exception so the client's r.json() never sees
+    // plain-text "Internal Server Error" bodies → prevents JSON.parse errors.
+    error(err: Error) {
+      console.error("[bractjs] unhandled server error:", err);
+      return new Response(JSON.stringify({ error: err.message }), {
+        status: 500,
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+      });
+    },
+  });
+
+  console.log(`[bract] Server running at http://localhost:${port}`);
+
+  return {
+    server,
+    stop() { server.stop(); },
+  };
+}
+
+// Allow running directly: bun run src/server/serve.ts
+if (import.meta.main) {
+  createServer();
+}

package/src/server/session.ts

@@ -0,0 +1,111 @@
+export type SessionData = Record<string, unknown>;
+
+export interface Session {
+  get(key: string): unknown;
+  set(key: string, val: unknown): void;
+  delete(key: string): void;
+  has(key: string): boolean;
+}
+
+export interface SessionStorage {
+  getSession(cookie?: string | null): Promise<Session>;
+  commitSession(session: Session, opts?: CommitOptions): Promise<string>;
+}
+
+export interface CookieSessionOptions {
+  name: string;
+  secrets: string[];
+  maxAge?: number;
+  secure?: boolean;
+  sameSite?: "Strict" | "Lax" | "None";
+}
+
+export interface CommitOptions {
+  maxAge?: number;
+}
+
+// Internal brand for accessing session data without exposing it on the public interface
+const DATA = Symbol("bract.session.data");
+interface InternalSession extends Session { [DATA]: SessionData }
+
+// ── Private helpers ─────────────────────────────────────────────────────────
+
+function encode(data: SessionData): string {
+  return btoa(JSON.stringify(data))
+    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function decode(encoded: string): SessionData {
+  const pad = "=".repeat((4 - (encoded.length % 4)) % 4);
+  return JSON.parse(atob(encoded.replace(/-/g, "+").replace(/_/g, "/") + pad)) as SessionData;
+}
+
+async function sign(data: string, secret: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw", enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" }, false, ["sign"],
+  );
+  const buf = await crypto.subtle.sign("HMAC", key, enc.encode(data));
+  return btoa(String.fromCharCode(...new Uint8Array(buf)))
+    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+async function verify(data: string, sig: string, secrets: string[]): Promise<boolean> {
+  for (const secret of secrets) {
+    const expected = await sign(data, secret);
+    if (expected.length === sig.length) {
+      let diff = 0;
+      for (let i = 0; i < expected.length; i++) diff |= expected.charCodeAt(i) ^ sig.charCodeAt(i);
+      if (diff === 0) return true;
+    }
+  }
+  return false;
+}
+
+function makeSession(data: SessionData): InternalSession {
+  return {
+    [DATA]: data,
+    get: (key) => data[key],
+    set: (key, val) => { data[key] = val; },
+    delete: (key) => { delete data[key]; },
+    has: (key) => key in data,
+  };
+}
+
+// ── Public API ──────────────────────────────────────────────────────────────
+
+export function createCookieSession(options: CookieSessionOptions): SessionStorage {
+  const { name, secrets, maxAge, secure = true, sameSite = "Lax" } = options;
+
+  return {
+    async getSession(cookie?: string | null): Promise<Session> {
+      if (!cookie) return makeSession({});
+      const pair = cookie.split(";").map((s) => s.trim()).find((p) => p.startsWith(`${name}=`));
+      if (!pair) return makeSession({});
+
+      const value = pair.slice(name.length + 1);
+      const dot = value.lastIndexOf(".");
+      if (dot === -1) return makeSession({});
+
+      const encoded = value.slice(0, dot);
+      const sig = value.slice(dot + 1);
+      if (!(await verify(encoded, sig, secrets))) return makeSession({});
+
+      try { return makeSession(decode(encoded)); }
+      catch { return makeSession({}); }
+    },
+
+    async commitSession(session: Session, opts?: CommitOptions): Promise<string> {
+      const data = (session as InternalSession)[DATA] ?? {};
+      const encoded = encode(data);
+      const sig = await sign(encoded, secrets[0]);
+      const age = opts?.maxAge ?? maxAge;
+
+      const parts = [`${name}=${encoded}.${sig}`, "HttpOnly", `SameSite=${sameSite}`, "Path=/"];
+      if (age !== undefined) parts.push(`Max-Age=${age}`);
+      if (secure) parts.push("Secure");
+      return parts.join("; ");
+    },
+  };
+}

package/src/server/static.ts

@@ -0,0 +1,40 @@
+import { join, resolve } from "node:path";
+
+const IMMUTABLE = "public, max-age=31536000, immutable";
+const NO_CACHE = "no-cache";
+
+/**
+ * Serve hashed client assets or public/ files.
+ * Returns null if the path doesn't match or the file isn't found.
+ * Guards against path traversal by resolving and prefix-checking.
+ */
+export async function serveStatic(
+  pathname: string,
+  buildDir: string,
+  publicDir: string,
+): Promise<Response | null> {
+  // Security: reject traversal sequences before any path resolution
+  if (pathname.includes("..")) return null;
+
+  if (pathname.startsWith("/build/client/")) {
+    const rel = pathname.slice("/build/client/".length);
+    const root = resolve(join(buildDir, "client"));
+    const full = resolve(join(root, rel));
+    if (!full.startsWith(root + "/") && full !== root) return null;
+    const file = Bun.file(full);
+    if (!(await file.exists())) return null;
+    return new Response(file, { headers: { "Cache-Control": IMMUTABLE } });
+  }
+
+  if (pathname.startsWith("/public/")) {
+    const rel = pathname.slice("/public/".length);
+    const root = resolve(publicDir);
+    const full = resolve(join(root, rel));
+    if (!full.startsWith(root + "/") && full !== root) return null;
+    const file = Bun.file(full);
+    if (!(await file.exists())) return null;
+    return new Response(file, { headers: { "Cache-Control": NO_CACHE } });
+  }
+
+  return null;
+}

package/src/shared/context.ts

@@ -0,0 +1,37 @@
+import { createContext, useContext, createElement, type ComponentType, type ReactNode } from "react";
+
+export interface RouteManifest {
+  [routeId: string]: {
+    file: string;
+    imports?: string[];
+  };
+}
+
+export interface BractJSContextValue {
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+  manifest: RouteManifest;
+  /** SSR-only: the matched route's default export so <Outlet> can render it without ClientRouter */
+  RouteComponent?: ComponentType;
+}
+
+export const BractJSContext = createContext<BractJSContextValue>(null!);
+
+interface BractJSProviderProps {
+  value: BractJSContextValue;
+  children: ReactNode;
+}
+
+export function BractJSProvider({ value, children }: BractJSProviderProps) {
+  return createElement(BractJSContext.Provider, { value }, children);
+}
+
+export function useBractJSContext(): BractJSContextValue {
+  const ctx = useContext(BractJSContext);
+  if (ctx === null) {
+    throw new Error("useBractJSContext must be used within a BractJSProvider");
+  }
+  return ctx;
+}

package/src/shared/deferred.ts

@@ -0,0 +1,55 @@
+const DEFERRED_MARKER = Symbol("bract.deferred");
+
+export class Deferred<T> {
+  readonly promise: Promise<T>;
+  readonly [DEFERRED_MARKER] = true as const;
+
+  constructor(promise: Promise<T>) {
+    this.promise = promise;
+  }
+}
+
+export type DeferredData<T extends Record<string, unknown>> = {
+  [K in keyof T]: T[K] extends Promise<infer V> ? Deferred<V> : T[K];
+};
+
+export function defer<T extends Record<string, unknown>>(
+  data: T
+): DeferredData<T> {
+  const result: Record<string, unknown> = {};
+
+  for (const key of Object.keys(data)) {
+    const value = data[key];
+    result[key] =
+      value instanceof Promise ? new Deferred(value) : value;
+  }
+
+  return result as DeferredData<T>;
+}
+
+export function isDeferred<T>(value: unknown): value is Deferred<T> {
+  return value instanceof Deferred;
+}
+
+/** Returns only the already-resolved (non-Promise) values from a DeferredData object. */
+export function stripDeferred<T extends Record<string, unknown>>(
+  data: T
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(data)) {
+    if (!isDeferred(data[key])) result[key] = data[key];
+  }
+  return result;
+}
+
+/** Returns only the deferred promises from a DeferredData object, keyed by field name. */
+export function promisesOf<T extends Record<string, unknown>>(
+  data: T
+): Record<string, Promise<unknown>> {
+  const result: Record<string, Promise<unknown>> = {};
+  for (const key of Object.keys(data)) {
+    const value = data[key];
+    if (isDeferred(value)) result[key] = (value as Deferred<unknown>).promise;
+  }
+  return result;
+}

package/src/shared/error-boundary.tsx

@@ -0,0 +1,58 @@
+import { Component, type ComponentType, type ReactNode, type ReactElement } from "react";
+
+// ── DefaultErrorBoundary ───────────────────────────────────────────────────
+
+interface DefaultErrorBoundaryProps {
+  error: Error;
+  requestId?: string;
+}
+
+export function DefaultErrorBoundary({ error, requestId }: DefaultErrorBoundaryProps): ReactElement {
+  if (process.env.NODE_ENV !== "production") {
+    return (
+      <div style={{ padding: "2rem", fontFamily: "monospace" }}>
+        <h2 style={{ color: "#e74c3c", margin: "0 0 1rem" }}>{error.message}</h2>
+        <pre style={{ overflow: "auto", background: "#111", color: "#f8f8f8", padding: "1rem" }}>
+          {error.stack}
+        </pre>
+        <button onClick={() => { void navigator.clipboard.writeText(error.stack ?? error.message); }}>
+          Copy stack
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ padding: "2rem" }}>
+      <h2>Something went wrong</h2>
+      {requestId && <p>Request ID: {requestId}</p>}
+    </div>
+  );
+}
+
+// ── RouteErrorBoundary ─────────────────────────────────────────────────────
+
+interface RouteErrorBoundaryProps {
+  errorBoundary?: ComponentType<{ error: Error }>;
+  children: ReactNode;
+}
+
+interface RouteErrorBoundaryState {
+  error: Error | null;
+}
+
+export class RouteErrorBoundary extends Component<RouteErrorBoundaryProps, RouteErrorBoundaryState> {
+  state: RouteErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): RouteErrorBoundaryState {
+    return { error };
+  }
+
+  render(): ReactNode {
+    if (this.state.error) {
+      const ErrorComponent = this.props.errorBoundary ?? DefaultErrorBoundary;
+      return <ErrorComponent error={this.state.error} />;
+    }
+    return this.props.children;
+  }
+}

package/src/shared/errors.ts

@@ -0,0 +1,49 @@
+export class BractJSError extends Error {
+  readonly status: number;
+
+  constructor(message: string, status: number = 500) {
+    super(message);
+    this.name = "BractJSError";
+    this.status = status;
+  }
+}
+
+export class HttpError extends BractJSError {
+  constructor(status: number, message?: string) {
+    super(message ?? httpStatusText(status), status);
+    this.name = "HttpError";
+  }
+}
+
+export function isRedirect(value: unknown): value is Response {
+  return (
+    value instanceof Response &&
+    value.status >= 300 &&
+    value.status < 400
+  );
+}
+
+export function isHttpError(value: unknown): value is HttpError {
+  return value instanceof HttpError;
+}
+
+export function isBractJSError(value: unknown): value is BractJSError {
+  return value instanceof BractJSError;
+}
+
+function httpStatusText(status: number): string {
+  const texts: Record<number, string> = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    503: "Service Unavailable",
+  };
+  return texts[status] ?? `HTTP Error ${status}`;
+}
+
+export { DefaultErrorBoundary, RouteErrorBoundary } from "./error-boundary.tsx";

package/src/shared/route-types.ts

@@ -0,0 +1,51 @@
+import type { Deferred } from "./deferred.ts";
+
+export interface LoaderArgs {
+  request: Request;
+  params: Record<string, string>;
+  context: Record<string, unknown>;
+}
+
+export interface ActionArgs extends LoaderArgs {
+  formData: FormData;
+}
+
+export type MetaDescriptor =
+  | { title: string }
+  | { name: string; content: string }
+  | { property: string; content: string }
+  | { [key: string]: string };
+
+export interface MetaArgs<T = unknown> {
+  loaderData: T;
+  params: Record<string, string>;
+}
+
+export type LoaderFunction<T = unknown> = (
+  args: LoaderArgs
+) => Promise<T | Response> | T | Response;
+
+export type ActionFunction<T = unknown> = (
+  args: ActionArgs
+) => Promise<T | Response> | T | Response;
+
+export type MetaFunction<T = unknown> = (
+  args: MetaArgs<T>
+) => MetaDescriptor[];
+
+export interface RouteModule<TLoader = unknown, TAction = unknown> {
+  loader?: LoaderFunction<TLoader>;
+  action?: ActionFunction<TAction>;
+  meta?: MetaFunction<TLoader>;
+  handle?: Record<string, unknown>;
+  ErrorBoundary?: React.ComponentType<{ error: unknown }>;
+  default?: React.ComponentType;
+}
+
+export interface RouteDefinition {
+  id: string;
+  path: string;
+  filePath: string;
+  parentId?: string;
+  index?: boolean;
+}

package/templates/new-app/app/root.tsx

@@ -0,0 +1,20 @@
+// This is the root layout for your BractJS app.
+// Every route renders inside this component.
+import { Scripts, LiveReload, Outlet } from "bractjs";
+
+export default function Root() {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>{{APP_NAME}}</title>
+      </head>
+      <body>
+        <Outlet />
+        <Scripts />
+        <LiveReload />
+      </body>
+    </html>
+  );
+}

package/templates/new-app/app/routes/_index.tsx

@@ -0,0 +1,31 @@
+import { useLoaderData } from "bractjs";
+import type { LoaderArgs } from "bractjs";
+import { Link } from "bractjs";
+
+interface HomeData {
+  message: string;
+}
+
+export async function loader(_args: LoaderArgs): Promise<HomeData> {
+  return { message: "Hello from BractJS!" };
+}
+
+export function meta() {
+  return [{ title: "Home | {{APP_NAME}}" }];
+}
+
+export default function Index() {
+  const { message } = useLoaderData<HomeData>();
+
+  return (
+    <main style={{ fontFamily: "system-ui, sans-serif", padding: "2rem" }}>
+      <h1>{message}</h1>
+      <p>
+        Edit <code>app/routes/_index.tsx</code> to get started.
+      </p>
+      <nav>
+        <Link to="/about">About →</Link>
+      </nav>
+    </main>
+  );
+}

package/templates/new-app/app/routes/about.tsx

@@ -0,0 +1,21 @@
+import { Link } from "bractjs";
+
+export function meta() {
+  return [{ title: "About | {{APP_NAME}}" }];
+}
+
+export default function About() {
+  return (
+    <main style={{ fontFamily: "system-ui, sans-serif", padding: "2rem" }}>
+      <h1>About</h1>
+      <p>
+        This app is built with{" "}
+        <a href="https://github.com/bractjs" target="_blank" rel="noreferrer">
+          BractJS
+        </a>{" "}
+        — an SSR framework for Bun + React 19.
+      </p>
+      <Link to="/">← Home</Link>
+    </main>
+  );
+}