@bractjs/bractjs 0.1.0

package/src/client/entry.tsx

@@ -0,0 +1,49 @@
+import { hydrateRoot } from "react-dom/client";
+import { type ReactElement, type ComponentType } from "react";
+import { ClientRouter } from "./ClientRouter.tsx";
+import { Outlet } from "./components/Outlet.tsx";
+import { matchPatternForPath } from "./nav-utils.ts";
+import type { BractJSClientData } from "./types.ts";
+import type { RouteModuleClient } from "./router.tsx";
+
+// ── Fallback App shell (used when rootChunk is missing) ────────────────────
+
+function FallbackApp(): ReactElement {
+  return <Outlet />;
+}
+
+// ── Hydration ──────────────────────────────────────────────────────────────
+
+// Wrapped in async IIFE so we can await module imports before hydrateRoot().
+// This prevents the SSR/client tree mismatch (server renders full root + route
+// component, client must start with the same tree shape).
+(async () => {
+  const data: BractJSClientData = window.__BRACTJS_DATA__;
+
+  // 1. Import the root component (app/root.tsx) so the client tree matches
+  //    the server-rendered shell (html, head, body, header, nav, etc.).
+  let RootComponent: ComponentType = FallbackApp;
+  if (data.manifest.rootChunk) {
+    const rootMod = await import(data.manifest.rootChunk);
+    if (rootMod.default) RootComponent = rootMod.default;
+  }
+
+  // 2. Pre-load the current route module so <Outlet> sees it during hydration.
+  let initialModule: RouteModuleClient | null = null;
+  const pattern = matchPatternForPath(data.pathname, data.manifest);
+  const chunkUrl = pattern !== null ? data.manifest.routes[pattern]?.chunk : undefined;
+
+  if (chunkUrl) {
+    initialModule = (await import(chunkUrl)) as RouteModuleClient;
+  } else if (data.routeFile) {
+    const url = `/_hmr/module?file=${encodeURIComponent(data.routeFile)}&t=0`;
+    initialModule = (await import(url)) as RouteModuleClient;
+  }
+
+  hydrateRoot(
+    document,
+    <ClientRouter initialData={data} initialModule={initialModule}>
+      <RootComponent />
+    </ClientRouter>,
+  );
+})();

package/src/client/form-utils.ts

@@ -0,0 +1,12 @@
+/**
+ * Fetches fresh loader data for a pathname and updates the router context.
+ */
+export async function reloadLoaders(
+  pathname: string,
+  setLoaderData: (data: Record<string, unknown>) => void,
+): Promise<void> {
+  const res = await fetch(`/_data?path=${encodeURIComponent(pathname)}`);
+  if (!res.ok) return;
+  const data = (await res.json()) as Record<string, unknown>;
+  setLoaderData(data);
+}

package/src/client/hooks/useActionData.ts

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+
+/**
+ * Returns the current route's action data, typed as T | null.
+ * Works in both SSR and client contexts.
+ */
+export function useActionData<T = unknown>(): T | null {
+  const router = useContext(RouterContext);
+  const bract = useContext(BractJSContext);
+  const actionData = router?.actionData ?? bract?.actionData ?? null;
+  return actionData as T | null;
+}

package/src/client/hooks/useFetcher.ts

@@ -0,0 +1,51 @@
+import { useState } from "react";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+type FetcherState = "idle" | "loading" | "submitting";
+
+interface SubmitOptions {
+  method: string;
+  body: FormData | Record<string, string>;
+}
+
+interface FetcherResult {
+  data: unknown;
+  state: FetcherState;
+  load(path: string): Promise<void>;
+  submit(path: string, opts: SubmitOptions): Promise<void>;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────────
+
+export function useFetcher(): FetcherResult {
+  const [data, setData] = useState<unknown>(undefined);
+  const [state, setState] = useState<FetcherState>("idle");
+
+  async function load(path: string): Promise<void> {
+    setState("loading");
+    try {
+      const res = await fetch(`/_data?path=${encodeURIComponent(path)}`);
+      const json = (await res.json()) as { route?: unknown };
+      setData(json.route);
+    } finally {
+      setState("idle");
+    }
+  }
+
+  async function submit(path: string, opts: 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 });
+      setData(await res.json());
+    } finally {
+      setState("idle");
+    }
+  }
+
+  return { data, state, load, submit };
+}

package/src/client/hooks/useLoaderData.ts

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+
+/**
+ * Returns the current route's loader data, typed as T.
+ * Works in both SSR and client contexts.
+ */
+export function useLoaderData<T = unknown>(): T {
+  const router = useContext(RouterContext);
+  const bract = useContext(BractJSContext);
+  const loaderData = router?.loaderData ?? bract?.loaderData ?? {};
+  return loaderData.route as T;
+}

package/src/client/hooks/useNavigation.ts

@@ -0,0 +1,12 @@
+import { useContext } from "react";
+import { NavigationContext } from "../router.tsx";
+import type { NavigationState } from "../router.tsx";
+
+/**
+ * Returns the current navigation state.
+ * Returns 'idle' during SSR (no NavigationContext present).
+ */
+export function useNavigation(): { state: NavigationState } {
+  const ctx = useContext(NavigationContext);
+  return { state: ctx?.state ?? "idle" };
+}

package/src/client/hooks/useParams.ts

@@ -0,0 +1,14 @@
+import { useContext } from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+
+/**
+ * Returns the current route's URL params (e.g. { id: "42" }).
+ * Pass a RouteParams<T> generic for typed params: useParams<RouteParams<"/blog/:id">>()
+ * Works in both SSR and client contexts.
+ */
+export function useParams<T extends Record<string, string> = Record<string, string>>(): T {
+  const router = useContext(RouterContext);
+  const bract = useContext(BractJSContext);
+  return (router?.params ?? bract?.params ?? {}) as T;
+}

package/src/client/nav-utils.ts

@@ -0,0 +1,35 @@
+import type { ServerManifest } from "../server/render.ts";
+
+// ── Pattern Matching ───────────────────────────────────────────────────────
+
+/**
+ * Tests whether a pathname matches a manifest route pattern.
+ * Pattern segments: "static", "[param]", "[...catchAll]"
+ */
+function patternMatches(pathname: string, pattern: string): boolean {
+  const pathSegs = pathname.replace(/^\//, "").split("/").filter(Boolean);
+  const patSegs = pattern === "" ? [] : pattern.split("/");
+  let p = 0;
+  for (const seg of patSegs) {
+    if (seg.startsWith("[...") && seg.endsWith("]")) return true; // catch-all: rest matches
+    if (p >= pathSegs.length) return false;
+    if (!(seg.startsWith("[") && seg.endsWith("]"))) {
+      if (seg !== pathSegs[p]) return false; // static: must be exact
+    }
+    p++; // param or matching static: consume one segment
+  }
+  return p === pathSegs.length;
+}
+
+// ── Export ─────────────────────────────────────────────────────────────────
+
+/** Returns the manifest pattern key that matches pathname, or null. */
+export function matchPatternForPath(
+  pathname: string,
+  manifest: ServerManifest,
+): string | null {
+  for (const pattern of Object.keys(manifest.routes)) {
+    if (patternMatches(pathname, pattern)) return pattern;
+  }
+  return null;
+}

package/src/client/prefetch.ts

@@ -0,0 +1,32 @@
+import type { ServerManifest } from "../server/render.ts";
+import { matchPatternForPath } from "./nav-utils.ts";
+
+// ── Cache ──────────────────────────────────────────────────────────────────
+
+const prefetched = new Set<string>();
+
+// ── Implementation ─────────────────────────────────────────────────────────
+
+/**
+ * Prefetches both the route chunk and loader data for the given path.
+ * De-duplicates via a module-level Set — safe to call on every hover.
+ */
+export function prefetchRoute(path: string, manifest: ServerManifest): void {
+  if (prefetched.has(path)) return;
+  prefetched.add(path);
+
+  // Prefetch route chunk via <link rel="modulepreload">
+  const pattern = matchPatternForPath(path, manifest);
+  const chunk = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
+  if (chunk) {
+    const link = document.createElement("link");
+    link.rel = "modulepreload";
+    link.href = chunk;
+    document.head.appendChild(link);
+  }
+
+  // Prefetch loader data at low priority
+  void fetch(`/_data?path=${encodeURIComponent(path)}`, {
+    priority: "low",
+  } as RequestInit);
+}

package/src/client/route-cache.ts

@@ -0,0 +1,20 @@
+import { lazy, type LazyExoticComponent, type ComponentType } from "react";
+
+// ── Route Cache ────────────────────────────────────────────────────────────
+
+// Keyed by chunkUrl so React.lazy is only created once per chunk.
+const routeCache = new Map<string, LazyExoticComponent<ComponentType>>();
+
+/**
+ * Returns a React.lazy component for the given chunk URL.
+ * Caches by chunkUrl so re-renders don't create new lazy references.
+ */
+export function getLazyRoute(chunkUrl: string): LazyExoticComponent<ComponentType> {
+  if (!routeCache.has(chunkUrl)) {
+    routeCache.set(
+      chunkUrl,
+      lazy(() => import(chunkUrl) as Promise<{ default: ComponentType }>),
+    );
+  }
+  return routeCache.get(chunkUrl)!;
+}

package/src/client/router.tsx

@@ -0,0 +1,54 @@
+import { createContext, useContext, type ComponentType } from "react";
+import type { ServerManifest } from "../server/render.ts";
+
+// ── Route module shape visible on the client ───────────────────────────────
+
+export interface RouteModuleClient {
+  default?: ComponentType;
+  ErrorBoundary?: ComponentType<{ error: Error }>;
+}
+
+// ── Router Context ─────────────────────────────────────────────────────────
+
+export interface RouteState {
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+}
+
+export interface RouterContextValue extends RouteState {
+  manifest: ServerManifest;
+  currentModule: RouteModuleClient | null;
+  setRoute(state: Partial<RouteState>): void;
+}
+
+export const RouterContext = createContext<RouterContextValue>(null!);
+
+export function useRouterContext(): RouterContextValue {
+  const ctx = useContext(RouterContext);
+  if (ctx === null) {
+    throw new Error("useRouterContext must be used within a ClientRouter");
+  }
+  return ctx;
+}
+
+// ── Navigation Context ─────────────────────────────────────────────────────
+
+export type NavigationState = "idle" | "loading" | "submitting";
+
+export interface NavigationContextValue {
+  state: NavigationState;
+  navigate(to: string): Promise<void>;
+  submit(to: string, options: { method: string; body: FormData | Record<string, string> }): Promise<void>;
+}
+
+export const NavigationContext = createContext<NavigationContextValue>(null!);
+
+export function useNavigationContext(): NavigationContextValue {
+  const ctx = useContext(NavigationContext);
+  if (ctx === null) {
+    throw new Error("useNavigationContext must be used within a ClientRouter");
+  }
+  return ctx;
+}

package/src/client/types.ts

@@ -0,0 +1,23 @@
+import type { ServerManifest } from "../server/render.ts";
+
+// ── BractJSClientData ────────────────────────────────────────────────────
+
+export interface BractJSClientData {
+  loaderData: Record<string, unknown>;
+  actionData: unknown;
+  params: Record<string, string>;
+  pathname: string;
+  manifest: ServerManifest;
+  /** Path of the matched route file, used to pre-import the module before hydration. */
+  routeFile?: string;
+}
+
+// ── Window augmentation ────────────────────────────────────────────────────
+
+declare global {
+  interface Window {
+    __BRACTJS_DATA__: BractJSClientData;
+    /** Dev-only: registered by ClientRouter for module-level HMR swaps. */
+    __BRACTJS_HMR_ACCEPT__?: (pattern: string, mod: Record<string, unknown>) => void;
+  }
+}

package/src/codegen/route-codegen.ts

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import { scanRoutes } from "../server/scanner.ts";
+import type { Segment } from "../server/scanner.ts";
+
+// Convert [param] / [...catchAll] notation to :param colon-style for URLs.
+function patternToColon(urlPattern: string): string {
+  if (urlPattern === "") return "/";
+  return "/" + urlPattern.split("/").map((seg) => {
+    if (seg.startsWith("[...") && seg.endsWith("]")) return ":" + seg.slice(4, -1);
+    if (seg.startsWith("[") && seg.endsWith("]")) return ":" + seg.slice(1, -1);
+    return seg;
+  }).join("/");
+}
+
+function paramsFromSegments(segments: Segment[]): string[] {
+  return segments.flatMap((seg) =>
+    typeof seg === "string" ? [] :
+    "param" in seg ? [seg.param] : [seg.catchAll],
+  );
+}
+
+// Replace each :paramName segment with ${params.paramName} for template literals.
+function substituteParams(pattern: string, params: string[]): string {
+  const set = new Set(params);
+  return pattern.split("/").map((seg) =>
+    seg.startsWith(":") && set.has(seg.slice(1))
+      ? "${params." + seg.slice(1) + "}"
+      : seg,
+  ).join("/");
+}
+
+function builderEntry(pattern: string, params: string[]): string {
+  if (params.length === 0)
+    return "  \"" + pattern + "\": () => \"" + pattern + "\" as const,";
+  const paramType = params.map((p) => p + ": string").join("; ");
+  const body = substituteParams(pattern, params);
+  return "  \"" + pattern + "\": (params: { " + paramType + " }) => `" + body + "` as const,";
+}
+
+function paramsTypeLines(routes: Array<{ pattern: string; params: string[] }>): string {
+  const dynamic = routes.filter((r) => r.params.length > 0);
+  if (dynamic.length === 0) return "export type RouteParams<_T extends AppRoutes> = Record<never, never>;";
+  const branches = dynamic
+    .map((r) =>
+      "  T extends \"" + r.pattern + "\" ? { "
+      + r.params.map((p) => p + ": string").join("; ")
+      + " } :",
+    )
+    .join("\n");
+  return "export type RouteParams<T extends AppRoutes> =\n" + branches + "\n  Record<never, never>;";
+}
+
+// Replaced at the top of the generated file.
+const HEADER =
+  "// Generated by `bractjs codegen` — do not edit manually.\n" +
+  "// Re-run with: bunx bractjs codegen\n" +
+  "\n" +
+  "/* eslint-disable */\n";
+
+export async function generateRouteTypes(appDir: string): Promise<string> {
+  const routeFiles = await scanRoutes(appDir);
+  const routes = routeFiles.map((r) => ({
+    pattern: patternToColon(r.urlPattern),
+    params: paramsFromSegments(r.segments),
+  }));
+
+  const union = routes.length > 0
+    ? routes.map((r) => "  | \"" + r.pattern + "\"").join("\n")
+    : "  never";
+
+  const builderEntries = routes.map((r) => builderEntry(r.pattern, r.params)).join("\n");
+
+  return [
+    HEADER,
+    "export type AppRoutes =",
+    union + ";",
+    "",
+    paramsTypeLines(routes),
+    "",
+    "export type TypedLoaderArgs<T extends AppRoutes> = {",
+    "  request: Request;",
+    "  params: RouteParams<T>;",
+    "  context: Record<string, unknown>;",
+    "};",
+    "export type TypedActionArgs<T extends AppRoutes> =",
+    "  TypedLoaderArgs<T> & { formData: FormData };",
+    "",
+    "export const routes = {",
+    builderEntries,
+    "} as const;",
+    "",
+  ].join("\n");
+}
+
+export async function writeRouteTypes(appDir: string, outPath?: string): Promise<void> {
+  const dest = outPath ?? join(appDir, "route-types.gen.ts");
+  await Bun.write(dest, await generateRouteTypes(appDir));
+  console.log("[bract] codegen →", dest);
+}

package/src/dev/error-overlay.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser-injected error overlay script.
+ * Listens for assignments to window.__BRACTJS_ERROR__ and renders a full-screen overlay.
+ */
+export const errorOverlayScript: string = `
+(function () {
+  Object.defineProperty(window, '__BRACTJS_ERROR__', {
+    set: function (err) {
+      var existing = document.getElementById('__bractjs_overlay__');
+      if (existing) existing.remove();
+      var msg = err && err.message ? err.message : String(err);
+      var stack = err && err.stack ? err.stack : '';
+      var overlay = document.createElement('div');
+      overlay.id = '__bractjs_overlay__';
+      overlay.style.cssText = [
+        'position:fixed', 'inset:0', 'background:#1a1a1a', 'color:#fff',
+        'padding:2rem', 'font-family:monospace', 'font-size:14px',
+        'border:4px solid #e74c3c', 'z-index:99999', 'overflow:auto'
+      ].join(';');
+      var h2 = document.createElement('h2');
+      h2.style.cssText = 'color:#e74c3c;margin:0 0 1rem';
+      h2.textContent = 'BractJS Error';
+      var pre = document.createElement('pre');
+      pre.style.cssText = 'white-space:pre-wrap';
+      pre.textContent = msg + (stack ? '\\n\\n' + stack : '');
+      overlay.appendChild(h2);
+      overlay.appendChild(pre);
+      document.body.appendChild(overlay);
+    },
+    configurable: true,
+  });
+})();
+`.trim();

package/src/dev/hmr-client.ts

@@ -0,0 +1,43 @@
+/**
+ * Browser-side HMR client script, embedded as a string and injected by LiveReload.
+ *
+ * Message types:
+ *   hmr:route  — swap a single route module without full page reload
+ *   hmr:reload — full page reload (root/layout/non-route file changed)
+ *
+ * Module swap flow:
+ *   1. Receive { type:"hmr:route", pattern, file }
+ *   2. Fetch /_hmr/module?file=<file>&t=<now> — server compiles it fresh
+ *   3. Call window.__BRACTJS_HMR_ACCEPT__(pattern, module)
+ *   4. ClientRouter swaps currentModule → React re-renders <Outlet>
+ */
+export const hmrClientScript: string = `
+(function () {
+  function connect() {
+    var ws = new WebSocket("ws://localhost:3001");
+    ws.onmessage = function (event) {
+      try {
+        var msg = JSON.parse(event.data);
+        if (msg.type === "hmr:reload") {
+          location.reload();
+        } else if (msg.type === "hmr:route" && msg.pattern != null && msg.chunkUrl) {
+          // 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.
+          var url = msg.chunkUrl + "?t=" + Date.now();
+          import(url).then(function (mod) {
+            var accept = window.__BRACTJS_HMR_ACCEPT__;
+            if (typeof accept === "function") {
+              accept(msg.pattern, mod);
+            } else {
+              location.reload();
+            }
+          }).catch(function () { location.reload(); });
+        }
+      } catch (_) {}
+    };
+    ws.onclose = function () { setTimeout(connect, 1000); };
+  }
+  connect();
+})();
+`.trim();

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

@@ -0,0 +1,47 @@
+import { resolve, join } from "node:path";
+
+/**
+ * Dev-only HTTP handler for /_hmr/module?file=routes/about.tsx
+ *
+ * Compiles the requested route file on-demand (in-memory, no outdir) and
+ * returns it as ESM so the browser can dynamically import it for module swap.
+ *
+ * Security: rejects any path that resolves outside appDir.
+ */
+export async function handleHmrModuleRequest(
+  url: URL,
+  appDir: string,
+): Promise<Response> {
+  const file = url.searchParams.get("file");
+  if (!file) {
+    return new Response("Missing file param", { status: 400 });
+  }
+
+  // Resolve and guard against path traversal
+  const rootDir = resolve(appDir);
+  const fullPath = resolve(join(rootDir, file));
+  if (!fullPath.startsWith(rootDir + "/") && fullPath !== rootDir) {
+    return new Response("Forbidden", { status: 403 });
+  }
+
+  // Build in-memory (no outdir → outputs held in memory, no disk write)
+  const result = await Bun.build({
+    entrypoints: [fullPath],
+    target: "browser",
+    minify: false,
+    sourcemap: "inline",
+  });
+
+  if (!result.success || result.outputs.length === 0) {
+    const msgs = result.logs.map((l) => String(l)).join("\n");
+    return new Response(`Build failed:\n${msgs}`, { status: 500 });
+  }
+
+  const js = await result.outputs[0].text();
+  return new Response(js, {
+    headers: {
+      "Content-Type": "text/javascript",
+      "Cache-Control": "no-store",
+    },
+  });
+}

package/src/dev/hmr-server.ts

@@ -0,0 +1,51 @@
+import type { ServerWebSocket } from "bun";
+
+// ── HMR Server ─────────────────────────────────────────────────────────────
+
+interface HmrMessage {
+  type: string;
+  file?: string;
+  duration?: number;
+  [key: string]: unknown;
+}
+
+const clients = new Set<ServerWebSocket<unknown>>();
+
+export function createHmrServer(port = 3001): {
+  broadcast(msg: HmrMessage): void;
+  stop(): void;
+} {
+  const server = Bun.serve({
+    port,
+    fetch(req, srv) {
+      if (srv.upgrade(req)) return undefined;
+      return new Response("HMR WebSocket endpoint", { status: 426 });
+    },
+    websocket: {
+      open(ws) {
+        clients.add(ws);
+      },
+      close(ws) {
+        clients.delete(ws);
+      },
+      message() {
+        // clients don't send messages
+      },
+    },
+  });
+
+  console.log(`HMR server on ws://localhost:${port}`);
+
+  return {
+    broadcast(msg: HmrMessage) {
+      const payload = JSON.stringify(msg);
+      for (const ws of clients) {
+        ws.send(payload);
+      }
+    },
+    stop() {
+      clients.clear();
+      server.stop(true);
+    },
+  };
+}