@bractjs/bractjs 0.1.0

package/src/build/directives.ts

@@ -0,0 +1,67 @@
+import type { BunPlugin } from "bun";
+
+const CLIENT_RE = /^["']use client["']/m;
+const SERVER_RE = /^["']use server["']/m;
+
+function extractExports(src: string): string[] {
+  const names: string[] = [];
+  for (const m of src.matchAll(/^export\s+(?:async\s+)?function\s+(\w+)/gm)) names.push(m[1]);
+  for (const m of src.matchAll(/^export\s+(?:let|const)\s+(\w+)\s*=/gm)) names.push(m[1]);
+  return names;
+}
+
+async function actionId(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);
+}
+
+/** Server build: stub "use client" modules → null components to prevent browser API crashes. */
+export const useClientStubPlugin: BunPlugin = {
+  name: "bractjs:use-client-stub",
+  setup(build) {
+    build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async ({ path }) => {
+      const src = await Bun.file(path).text();
+      if (!CLIENT_RE.test(src)) return undefined;
+      const stubs = extractExports(src).map((n) => `export const ${n} = () => null;`).join("\n");
+      return { contents: stubs || "export {};", loader: "ts" };
+    });
+  },
+};
+
+// Async fetch helper inlined into every generated "use server" proxy module.
+const PROXY_HELPER = `async function __bract(id: string, args: unknown[]): Promise<unknown> {
+  const isForm = args.length === 1 && args[0] instanceof FormData;
+  const r = await fetch("/_action?id=" + encodeURIComponent(id), {
+    method: "POST",
+    headers: isForm
+      ? { "X-BractJS-Action": "1" }
+      : { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+    body: isForm ? (args[0] as FormData) : JSON.stringify(args),
+  });
+  if (!r.ok) throw new Error("[bractjs] action " + id + " failed: " + r.status);
+  return r.json() as Promise<unknown>;
+}`;
+
+/** Client build: replace "use server" exports with fetch proxy stubs. */
+export const useServerProxyPlugin: BunPlugin = {
+  name: "bractjs:use-server-proxy",
+  setup(build) {
+    build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async ({ path }) => {
+      const src = await Bun.file(path).text();
+      if (!SERVER_RE.test(src)) return undefined;
+      const names = extractExports(src);
+      if (names.length === 0) return { contents: "export {};", loader: "ts" };
+      const proxies = await Promise.all(
+        names.map(async (name) => {
+          const id = await actionId(path, name);
+          return `export const ${name} = (...args: unknown[]) => __bract("${id}", args);`;
+        }),
+      );
+      return { contents: PROXY_HELPER + "\n" + proxies.join("\n"), loader: "ts" };
+    });
+  },
+};

package/src/build/env-plugin.ts

@@ -0,0 +1,56 @@
+import type { BunPlugin } from "bun";
+
+// ── Server-only import guard ───────────────────────────────────────────────
+
+/**
+ * Blocks any import matching *.server.ts / *.server.tsx during client builds.
+ * Uses a two-step plugin: onResolve redirects to a virtual namespace,
+ * then onLoad throws a hard build error.
+ */
+export const serverOnlyPlugin: BunPlugin = {
+  name: "bractjs-server-only",
+  setup(build) {
+    build.onResolve({ filter: /\.server(\.(tsx?|jsx?))?$/ }, (args) => ({
+      path: args.path,
+      namespace: "bractjs-server-only",
+    }));
+
+    build.onLoad(
+      { filter: /.*/, namespace: "bractjs-server-only" },
+      (args) => {
+        throw new Error(
+          `[BractJS] Cannot import "${args.path}" in client code.\n` +
+            `Move this to a loader() or action().`,
+        );
+      },
+    );
+  },
+};
+
+// ── Client env allowlist ───────────────────────────────────────────────────
+
+/**
+ * Replaces process.env.KEY with string literals for allowed keys.
+ * All other process.env.* references become the string "undefined".
+ */
+export function clientEnvPlugin(
+  allowedKeys: string[],
+  envValues: Record<string, string>,
+): BunPlugin {
+  return {
+    name: "bractjs-client-env",
+    setup(build) {
+      build.onLoad({ filter: /\.(ts|tsx|js|jsx)$/ }, async (args) => {
+        const src = await Bun.file(args.path).text();
+        const contents = src.replace(
+          /process\.env\.([A-Z_][A-Z0-9_]*)/g,
+          (_match, key: string) =>
+            allowedKeys.includes(key)
+              ? JSON.stringify(envValues[key] ?? "")
+              : '"undefined"',
+        );
+        return { contents, loader: args.loader };
+      });
+    },
+  };
+}

package/src/build/hash.ts

@@ -0,0 +1,56 @@
+import { extname, basename, dirname, join } from "node:path";
+import { test, expect } from "bun:test";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+async function digestToHex(buffer: ArrayBuffer): Promise<string> {
+  const hashBuffer = await crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(hashBuffer))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+
+/** SHA-256 of file contents → first 8 hex chars. */
+export async function contentHash(filePath: string): Promise<string> {
+  const buffer = await Bun.file(filePath).arrayBuffer();
+  return (await digestToHex(buffer)).slice(0, 8);
+}
+
+/** SHA-256 of a string → first 8 hex chars. */
+export async function hashString(content: string): Promise<string> {
+  const buffer = new TextEncoder().encode(content).buffer as ArrayBuffer;
+  return (await digestToHex(buffer)).slice(0, 8);
+}
+
+/**
+ * Inserts the content hash before the file extension.
+ * Example: client.js → client.abc12345.js
+ * Returns the new path (does NOT rename on disk).
+ */
+export async function renameWithHash(filePath: string): Promise<string> {
+  const hash = await contentHash(filePath);
+  const ext = extname(filePath);
+  const base = basename(filePath, ext);
+  return join(dirname(filePath), `${base}.${hash}${ext}`);
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+test("same content → same hash", async () => {
+  const a = await hashString("hello world");
+  const b = await hashString("hello world");
+  expect(a).toBe(b);
+});
+
+test("different content → different hash", async () => {
+  const a = await hashString("foo");
+  const b = await hashString("bar");
+  expect(a).not.toBe(b);
+});
+
+test("hash is 8 hex chars", async () => {
+  const h = await hashString("bractjs");
+  expect(h).toMatch(/^[0-9a-f]{8}$/);
+});

package/src/build/manifest.ts

@@ -0,0 +1,60 @@
+import { join } from "node:path";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface RouteManifestEntry {
+  chunk: string;
+  pattern: string;
+}
+
+export interface RouteManifest {
+  version: 1;
+  clientEntry: string;
+  rootChunk?: string;
+  routes: Record<string, RouteManifestEntry>;
+}
+
+// ── Module-scope cache ─────────────────────────────────────────────────────
+
+let cached: RouteManifest | null = null;
+
+// ── Functions ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a RouteManifest from hashed output paths.
+ * @param opts.clientEntry   Hashed path to main client bundle
+ * @param opts.routeChunks  Map<urlPattern, hashedChunkPath>
+ */
+export function generateManifest(opts: {
+  clientEntry: string;
+  rootChunk?: string;
+  routeChunks: Map<string, string>;
+}): RouteManifest {
+  const routes: Record<string, RouteManifestEntry> = {};
+  for (const [pattern, chunk] of opts.routeChunks) {
+    routes[pattern] = { chunk, pattern };
+  }
+  return { version: 1, clientEntry: opts.clientEntry, rootChunk: opts.rootChunk, routes };
+}
+
+/**
+ * Write manifest to {outDir}/route-manifest.json (pretty-printed).
+ */
+export async function writeManifest(
+  manifest: RouteManifest,
+  outDir: string,
+): Promise<void> {
+  const dest = join(outDir, "route-manifest.json");
+  await Bun.write(dest, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Load and cache the manifest from disk.
+ * Call this at production server startup.
+ */
+export async function loadManifest(buildDir: string): Promise<RouteManifest> {
+  if (cached) return cached;
+  const src = join(buildDir, "route-manifest.json");
+  cached = (await Bun.file(src).json()) as RouteManifest;
+  return cached;
+}

package/src/client/ClientRouter.tsx

@@ -0,0 +1,122 @@
+import {
+  useState, useCallback, useEffect, startTransition,
+  type ReactNode, type ReactElement,
+} from "react";
+import {
+  RouterContext,
+  NavigationContext,
+  type RouteState,
+  type NavigationState,
+  type RouteModuleClient,
+} from "./router.tsx";
+import type { ServerManifest } from "../server/render.ts";
+import { matchPatternForPath } from "./nav-utils.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+export interface BractJSInitialData extends RouteState {
+  manifest: ServerManifest;
+}
+
+interface ClientRouterProps {
+  children: ReactNode;
+  initialData: BractJSInitialData;
+  initialModule?: RouteModuleClient | null;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function ClientRouter({ children, initialData, initialModule = null }: ClientRouterProps): ReactElement {
+  const [loaderData, setLoaderData] = useState(initialData.loaderData);
+  const [actionData, setActionData] = useState<unknown>(initialData.actionData);
+  const [params, setParams] = useState(initialData.params);
+  const [pathname, setPathname] = useState(initialData.pathname);
+  const [navState, setNavState] = useState<NavigationState>("idle");
+  const [currentModule, setCurrentModule] = useState<RouteModuleClient | null>(initialModule);
+
+  const manifest = initialData.manifest;
+
+  const setRoute = useCallback((state: Partial<RouteState>) => {
+    if (state.loaderData !== undefined) setLoaderData(state.loaderData);
+    if (state.actionData !== undefined) setActionData(state.actionData);
+    if (state.params !== undefined) setParams(state.params);
+    if (state.pathname !== undefined) setPathname(state.pathname);
+  }, []);
+
+  /** Load route data + module without touching history. */
+  const loadRoute = useCallback(async (to: string) => {
+    setNavState("loading");
+    try {
+      const pattern = matchPatternForPath(to, manifest);
+      const chunkUrl = pattern !== null ? manifest.routes[pattern]?.chunk : undefined;
+      const [routeModule, res] = await Promise.all([
+        chunkUrl ? import(/* @vite-ignore */ chunkUrl) : Promise.resolve(null),
+        fetch(`/_data?path=${encodeURIComponent(to)}`),
+      ]);
+      // Guard: always parse JSON, but only when the server signals success.
+      // Without r.ok check, a Bun 500 plain-text response causes
+      // SyntaxError: JSON.parse: unexpected character — an unhandled rejection.
+      if (!res.ok) {
+        console.error(`[bractjs] /_data ${res.status} for ${to}`);
+        setNavState("idle");
+        return;
+      }
+      const data = await res.json() as Record<string, unknown>;
+      startTransition(() => {
+        setLoaderData(data);
+        setParams((data.params as Record<string, string>) ?? {});
+        setPathname(to);
+        setCurrentModule(routeModule);
+      });
+      if ((data.meta as { title?: string })?.title) {
+        document.title = (data.meta as { title: string }).title;
+      }
+    } catch (err) {
+      console.error("[bractjs] loadRoute error:", err);
+    } finally {
+      setNavState("idle");
+    }
+  }, [manifest]);
+
+  const navigate = useCallback(async (to: string) => {
+    await loadRoute(to);
+    history.pushState({}, "", to);
+  }, [loadRoute]);
+
+  // Handle browser back / forward
+  useEffect(() => {
+    const onPopState = () => { void loadRoute(location.pathname); };
+    window.addEventListener("popstate", onPopState);
+    return () => window.removeEventListener("popstate", onPopState);
+  }, [loadRoute]);
+
+  // Module-level HMR: swap the current route module without a full reload.
+  // The injected HMR client script calls window.__BRACTJS_HMR_ACCEPT__(pattern, mod)
+  // after importing the freshly-built chunk from /_hmr/module.
+  useEffect(() => {
+    if (process.env.NODE_ENV === "production") return;
+    const w = window as unknown as { __BRACTJS_HMR_ACCEPT__?: unknown };
+    w.__BRACTJS_HMR_ACCEPT__ = (pattern: string, mod: RouteModuleClient) => {
+      const current = matchPatternForPath(pathname, manifest);
+      if (current === pattern) startTransition(() => setCurrentModule(mod));
+    };
+    return () => { delete w.__BRACTJS_HMR_ACCEPT__; };
+  }, [pathname, manifest]);
+
+  // Stub — real implementation in Prompt 2.6
+  const submit = useCallback(async (
+    _to: string,
+    _opts: { method: string; body: FormData | Record<string, string> },
+  ) => {
+    setNavState("submitting");
+    setNavState("idle");
+  }, []);
+
+  return (
+    <RouterContext.Provider value={{ loaderData, actionData, params, pathname, manifest, currentModule, setRoute }}>
+      <NavigationContext.Provider value={{ state: navState, navigate, submit }}>
+        {children}
+      </NavigationContext.Provider>
+    </RouterContext.Provider>
+  );
+}

package/src/client/components/Await.tsx

@@ -0,0 +1,26 @@
+import { Suspense, use, type ReactNode } from "react";
+
+interface AwaitProps<T> {
+  resolve: Promise<T>;
+  fallback: ReactNode;
+  children: (data: T) => ReactNode;
+}
+
+/**
+ * Unwraps a promise using React 19's `use()` API.
+ * The nearest <Suspense> boundary (provided by <Await> itself) handles the
+ * pending state by rendering `fallback`. On resolve, `children` is called
+ * with the resolved value.
+ */
+function Resolved<T>({ resolve, children }: Pick<AwaitProps<T>, "resolve" | "children">) {
+  const data = use(resolve);
+  return <>{children(data)}</>;
+}
+
+export function Await<T>({ resolve, fallback, children }: AwaitProps<T>) {
+  return (
+    <Suspense fallback={fallback}>
+      <Resolved resolve={resolve}>{children}</Resolved>
+    </Suspense>
+  );
+}

package/src/client/components/Form.tsx

@@ -0,0 +1,67 @@
+import { useContext, type FormEvent, type ReactNode, type FormHTMLAttributes } from "react";
+import { RouterContext, NavigationContext } from "../router.tsx";
+import { reloadLoaders } from "../form-utils.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+type FormMethod = "post" | "put" | "delete";
+
+interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "method" | "onSubmit"> {
+  method?: FormMethod;
+  action?: string;
+  children: ReactNode;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function Form({ method = "post", action, children, ...rest }: FormProps) {
+  const routerCtx = useContext(RouterContext);
+  const navCtx = useContext(NavigationContext);
+
+  // SSR: render a plain form — no JS submit handler needed
+  if (!routerCtx || !navCtx) {
+    return (
+      <form method={method} action={action} {...rest}>
+        {children}
+      </form>
+    );
+  }
+
+  const { pathname, setRoute } = routerCtx;
+  const { navigate } = navCtx;
+
+  // setLoaderData shim — updates just the loaderData slice via setRoute
+  function setLoaderData(data: Record<string, unknown>) {
+    setRoute({ loaderData: data });
+  }
+
+  async function handleSubmit(e: FormEvent<HTMLFormElement>) {
+    e.preventDefault();
+    setRoute({ actionData: null }); // clear stale action data
+
+    const target = e.currentTarget;
+    const url = action ?? pathname;
+    const formData = new FormData(target);
+
+    const response = await fetch(url, {
+      method: method.toUpperCase(),
+      body: formData,
+      headers: { "X-BractJS-Action": "1" },
+    });
+
+    if (response.redirected) {
+      await navigate(response.url);
+      return;
+    }
+
+    const actionData = (await response.json()) as unknown;
+    setRoute({ actionData });
+    await reloadLoaders(pathname, setLoaderData);
+  }
+
+  return (
+    <form method={method} onSubmit={(e) => { void handleSubmit(e); }} {...rest}>
+      {children}
+    </form>
+  );
+}

package/src/client/components/Image.tsx

@@ -0,0 +1,79 @@
+import type { CSSProperties } from "react";
+
+export type ImageFormat = "webp" | "avif" | "jpeg" | "png";
+export type ImageFit = "cover" | "contain" | "fill";
+
+export interface ImageProps {
+  /** Must be a path under /public/, e.g. /public/hero.jpg */
+  src: string;
+  alt: string;
+  width?: number;
+  height?: number;
+  quality?: number;
+  format?: ImageFormat;
+  fit?: ImageFit;
+  /** Disables lazy loading and sets fetchpriority=high (above-the-fold images). */
+  priority?: boolean;
+  sizes?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const WIDTHS = [320, 640, 768, 1024, 1280, 1536, 1920];
+
+function imgUrl(src: string, w: number, q: number, format: ImageFormat, fit: ImageFit): string {
+  const sp = new URLSearchParams({
+    src,
+    w: String(w),
+    q: String(q),
+    format,
+    fit,
+  });
+  return `/_image?${sp.toString()}`;
+}
+
+export function Image({
+  src,
+  alt,
+  width,
+  height,
+  quality = 80,
+  format = "webp",
+  fit = "cover",
+  priority = false,
+  sizes = "100vw",
+  className,
+  style,
+}: ImageProps) {
+  // Only include widths up to 1.5× the declared intrinsic width to avoid
+  // generating unnecessarily large variants.
+  const widths = width
+    ? WIDTHS.filter((w) => w <= Math.ceil(width * 1.5))
+    : WIDTHS;
+
+  // Ensure at least one srcset entry even if widths filtered to empty.
+  const srcWidths = widths.length > 0 ? widths : [width ?? 1280];
+
+  const srcset = srcWidths
+    .map((w) => `${imgUrl(src, w, quality, format, fit)} ${w}w`)
+    .join(", ");
+
+  const defaultSrc = imgUrl(src, width ?? 1280, quality, format, fit);
+
+  return (
+    <img
+      src={defaultSrc}
+      srcSet={srcset}
+      alt={alt}
+      width={width}
+      height={height}
+      loading={priority ? "eager" : "lazy"}
+      decoding={priority ? "sync" : "async"}
+      // @ts-expect-error — fetchpriority is a valid HTML attribute in React 19
+      fetchpriority={priority ? "high" : "auto"}
+      sizes={sizes}
+      className={className}
+      style={style}
+    />
+  );
+}

package/src/client/components/Link.tsx

@@ -0,0 +1,42 @@
+import { useContext, type AnchorHTMLAttributes, type ReactNode } from "react";
+import { NavigationContext, RouterContext } from "../router.tsx";
+import { prefetchRoute } from "../prefetch.ts";
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href"> {
+  to: string;
+  prefetch?: "hover" | "none";
+  children: ReactNode;
+}
+
+// ── Component ──────────────────────────────────────────────────────────────
+
+export function Link({ to, prefetch = "none", children, ...rest }: LinkProps) {
+  const navCtx = useContext(NavigationContext);
+  const routerCtx = useContext(RouterContext);
+  const isLoading = navCtx?.state === "loading";
+
+  function handleClick(e: React.MouseEvent<HTMLAnchorElement>) {
+    if (!navCtx) return; // SSR: let browser handle naturally
+    if (e.ctrlKey || e.metaKey || e.shiftKey || e.altKey) return;
+    e.preventDefault();
+    void navCtx.navigate(to);
+  }
+
+  function handleMouseEnter() {
+    if (prefetch === "hover" && routerCtx) prefetchRoute(to, routerCtx.manifest);
+  }
+
+  return (
+    <a
+      href={to}
+      onClick={handleClick}
+      onMouseEnter={handleMouseEnter}
+      aria-disabled={isLoading || undefined}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+}

package/src/client/components/LiveReload.tsx

@@ -0,0 +1,16 @@
+import { type ReactElement } from "react";
+import { hmrClientScript } from "../../dev/hmr-client.ts";
+
+/**
+ * Renders an inline WebSocket HMR client in development.
+ * Returns null in production.
+ */
+export function LiveReload(): ReactElement | null {
+  if (process.env.NODE_ENV === "production") return null;
+
+  return (
+    <script
+      dangerouslySetInnerHTML={{ __html: hmrClientScript }}
+    />
+  );
+}

package/src/client/components/Outlet.tsx

@@ -0,0 +1,64 @@
+import {
+  Component, Suspense, useContext,
+  type ComponentType, type ReactElement, type ReactNode,
+} from "react";
+import { RouterContext } from "../router.tsx";
+import { BractJSContext } from "../../shared/context.ts";
+
+// ── Error Boundary ─────────────────────────────────────────────────────────
+
+interface EBProps {
+  fallback: ComponentType<{ error: Error }>;
+  children: ReactNode;
+}
+interface EBState { error: Error | null }
+
+class RouteErrorBoundary extends Component<EBProps, EBState> {
+  state: EBState = { error: null };
+
+  static getDerivedStateFromError(error: Error): EBState {
+    return { error };
+  }
+
+  render(): ReactNode {
+    if (this.state.error) {
+      const Fallback = this.props.fallback;
+      return <Fallback error={this.state.error} />;
+    }
+    return this.props.children;
+  }
+}
+
+function DefaultErrorFallback({ error }: { error: Error }): ReactElement {
+  return <div style={{ color: "red" }}>Route error: {error.message}</div>;
+}
+
+// ── Outlet ─────────────────────────────────────────────────────────────────
+
+export function Outlet(): ReactElement | null {
+  // Client-side: use RouterContext (set by ClientRouter after navigation)
+  const routerCtx = useContext(RouterContext);
+  // Server-side (SSR): fall back to BractJSContext which carries RouteComponent
+  const bractCtx = useContext(BractJSContext);
+
+  const RouteComponent: ComponentType | undefined =
+    routerCtx?.currentModule?.default ?? bractCtx?.RouteComponent;
+  const ErrorFallback: ComponentType<{ error: Error }> =
+    routerCtx?.currentModule?.ErrorBoundary ?? DefaultErrorFallback;
+
+  if (!RouteComponent) {
+    return (
+      <Suspense fallback={null}>
+        {null}
+      </Suspense>
+    );
+  }
+
+  return (
+    <RouteErrorBoundary fallback={ErrorFallback}>
+      <Suspense fallback={null}>
+        <RouteComponent />
+      </Suspense>
+    </RouteErrorBoundary>
+  );
+}

package/src/client/components/Scripts.tsx

@@ -0,0 +1,12 @@
+/**
+ * Scripts is a marker component.
+ * Bract's SSR render pipeline injects the client entry script and
+ * bootstrap data via `bootstrapScripts` and `bootstrapScriptContent`
+ * in renderToReadableStream — not through this component.
+ *
+ * At runtime this returns null; its presence in the component tree
+ * signals to the framework where scripts logically belong in the layout.
+ */
+export function Scripts(): null {
+  return null;
+}