@bractjs/bractjs 0.1.24 → 0.1.26

package/src/build/env-plugin.ts

@@ -1,10 +1,19 @@
 import type { BunPlugin } from "bun";
 import { resolve } from "node:path";
+import { extractExports } from "./directives.ts";
 
-// Resolved at module load so the lookup is cheap (every onLoad call uses it).
-// Equivalent to the absolute path of the directory holding this file
-// (`<bractjs>/src/build/`). We strip `/src/build` to get the framework root.
-const FRAMEWORK_SRC_ROOT = resolve(import.meta.dir, "..");
+// Lazy: this module is re-exported from the package barrel, so it may be
+// statically pulled into client bundles. `import.meta.dir` is undefined in the
+// browser, and a top-level `resolve(import.meta.dir, "..")` would throw
+// "Path must be a string" at module load — before any plugin is even invoked.
+// Defer the resolve until a plugin actually runs (always server-side).
+let frameworkSrcRoot: string | undefined;
+function getFrameworkSrcRoot(): string {
+  if (frameworkSrcRoot === undefined) {
+    frameworkSrcRoot = resolve(import.meta.dir, "..");
+  }
+  return frameworkSrcRoot;
+}
 
 // ── Server-only import guard ───────────────────────────────────────────────
 
@@ -33,6 +42,68 @@ export const serverOnlyPlugin: BunPlugin = {
   },
 };
 
+// ── Server-only module stub ────────────────────────────────────────────────
+
+const SERVER_FILE_RE = /\.server\.(tsx?|jsx?)$/;
+const DEFAULT_EXPORT_RE = /^export\s+default\b/m;
+
+// Runtime stub injected for every named/default export of a `*.server.ts`
+// module on the client. It is a callable Proxy that throws on call AND on
+// property access, so:
+//   • the route module's loader/action keep referencing the symbols (the
+//     bundle still resolves `import { db } from "./db.server.ts"`), and
+//   • the bodies are inert dead code on the client (the server runs them), but
+//   • any *accidental* use from real client code throws a clear error instead
+//     of silently shipping a broken `undefined`.
+const SERVER_STUB_FACTORY = `const __bractServerStub = (name) => {
+  const fail = () => {
+    throw new Error(
+      "[BractJS] '" + name + "' comes from a *.server.ts module and is not " +
+      "available in the browser. Call it only inside a loader() or action()."
+    );
+  };
+  return new Proxy(fail, { get: (_t, prop) => (prop === "name" ? name : fail()), apply: fail });
+};`;
+
+/**
+ * Client build: replace every export of a `*.server.ts` module with an inert
+ * stub instead of hard-failing the build.
+ *
+ * BractJS ships the *entire* route module — loader and action included — to the
+ * client bundle (the server never strips them). A route that legitimately does
+ * `import { db } from "./db.server.ts"` inside its loader therefore drags the
+ * server module into the client graph. Hard-failing that import (the old
+ * `serverOnlyPlugin` behaviour) made the documented "import a server module in
+ * a loader" pattern impossible. Stubbing instead:
+ *   - keeps named/default imports resolvable, so the route module compiles,
+ *   - guarantees **zero** server source (DB drivers, secrets, `bun:sqlite`,
+ *     etc.) reaches the browser — the original file is never read for content,
+ *   - throws loudly if a stub is ever actually used on the client.
+ *
+ * Loaders/actions are dead code on the client (only the server invokes them),
+ * so the stubs are never called in correct usage.
+ */
+export const serverModuleStubPlugin: BunPlugin = {
+  name: "bractjs-server-module-stub",
+  setup(build) {
+    build.onLoad({ filter: SERVER_FILE_RE }, async ({ path }) => {
+      const src = await Bun.file(path).text();
+      const names = extractExports(src);
+      const lines = [SERVER_STUB_FACTORY];
+      for (const name of names) {
+        lines.push(`export const ${name} = __bractServerStub(${JSON.stringify(name)});`);
+      }
+      if (DEFAULT_EXPORT_RE.test(src)) {
+        lines.push(`export default __bractServerStub("default");`);
+      }
+      // `export {};` guarantees the module is treated as ESM even when the
+      // server file had no statically-detectable exports.
+      lines.push("export {};");
+      return { contents: lines.join("\n"), loader: "ts" };
+    });
+  },
+};
+
 // ── Client env allowlist ───────────────────────────────────────────────────
 
 /**
@@ -56,7 +127,7 @@ export function clientEnvPlugin(
         // the client. Without this guard, linking the framework via `file:`
         // produces a build that fails to parse its own source.
         if (args.path.includes("/node_modules/")) return undefined;
-        if (args.path.startsWith(FRAMEWORK_SRC_ROOT)) return undefined;
+        if (args.path.startsWith(getFrameworkSrcRoot())) return undefined;
         const src = await Bun.file(args.path).text();
         // SECURITY(medium): textual regex replace runs over the whole source,
         // including inside string literals and comments. A bare `process.env.X`

package/src/build/react-dedupe.ts

@@ -0,0 +1,41 @@
+import type { BunPlugin } from "bun";
+
+/**
+ * Force every `react` / `react-dom` import in the CLIENT bundle to resolve to a
+ * single physical copy (the app's cwd copy).
+ *
+ * The client build mixes entrypoints from two roots: the framework's
+ * `src/client/entry.tsx` (which resolves react from the framework's
+ * node_modules) and the app's route files (which resolve react from the app's
+ * node_modules). When the `file:..`-linked framework carries its own react copy
+ * — even at the same version — those are two distinct module instances. The
+ * result is a dual-React "invalid hook call" (`ReactSharedInternals.H` is null)
+ * the moment a `"use client"` component runs a hook during hydration.
+ *
+ * Pinning all react specifiers to one resolved path eliminates the duplication.
+ */
+const REACT_RE = /^(react|react-dom)(\/.*)?$/;
+
+export function reactDedupePlugin(appCwd: string = process.cwd()): BunPlugin {
+  const cache = new Map<string, string>();
+  const resolveOne = (spec: string): string | null => {
+    if (cache.has(spec)) return cache.get(spec)!;
+    try {
+      const resolved = Bun.resolveSync(spec, appCwd);
+      cache.set(spec, resolved);
+      return resolved;
+    } catch {
+      return null;
+    }
+  };
+
+  return {
+    name: "bractjs:react-dedupe",
+    setup(build) {
+      build.onResolve({ filter: REACT_RE }, (args) => {
+        const resolved = resolveOne(args.path);
+        return resolved ? { path: resolved } : undefined;
+      });
+    },
+  };
+}

package/src/client/ClientRouter.tsx

@@ -10,13 +10,16 @@ import {
   type RouteModuleClient,
 } from "./router.tsx";
 import type { ServerManifest } from "../server/render.ts";
-import { matchPatternForPath } from "./nav-utils.ts";
+import { matchPatternForPath, toSamePath } from "./nav-utils.ts";
 import { loaderCache, cacheKey } from "./cache.ts";
+import { MetaTags } from "../shared/meta-tags.tsx";
+import type { MetaDescriptor } from "../shared/route-types.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
 export interface BractJSInitialData extends RouteState {
   manifest: ServerManifest;
+  meta?: MetaDescriptor[];
 }
 
 interface ClientRouterProps {
@@ -34,6 +37,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   const [pathname, setPathname] = useState(initialData.pathname);
   const [navState, setNavState] = useState<NavigationState>("idle");
   const [currentModule, setCurrentModule] = useState<RouteModuleClient | null>(initialModule);
+  const [meta, setMeta] = useState<MetaDescriptor[]>(initialData.meta ?? []);
 
   const manifest = initialData.manifest;
 
@@ -50,6 +54,15 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   /** Load route data + module without touching history. */
   const loadRoute = useCallback(async (to: string) => {
     setNavState("loading");
+    // Follow a redirect Location from client-side beforeLoad. Same-origin
+    // targets stay in the SPA; an off-origin/protocol-relative Location is NOT
+    // fed to the router — we do a full-page navigation so the browser's own
+    // cross-origin handling applies and we never open-redirect via pushState.
+    const followRedirect = (loc: string) => {
+      const safe = toSamePath(loc);
+      if (safe) { void navigateRef.current(safe); return; }
+      window.location.href = loc;
+    };
     try {
       const toPathname = to.split("?")[0];
       const pattern = matchPatternForPath(toPathname, manifest);
@@ -75,12 +88,12 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
           });
           if (result instanceof Response) {
             const loc = result.headers.get("Location");
-            if (loc) { void navigateRef.current(loc); return; }
+            if (loc) { followRedirect(loc); return; }
           }
         } catch (err) {
           if (err instanceof Response) {
             const loc = (err as Response).headers.get("Location");
-            if (loc) { void navigateRef.current(loc); return; }
+            if (loc) { followRedirect(loc); return; }
           }
           throw err;
         }
@@ -176,11 +189,11 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
         setPathname(to);
         setCurrentModule(routeModule);
       });
-      const metaList = data.meta as Array<Record<string, unknown>> | undefined;
-      const titleEntry = metaList?.find((m) => "title" in m);
-      if (titleEntry && typeof titleEntry.title === "string") {
-        document.title = titleEntry.title;
-      }
+      // Re-render the document head from the new route's merged meta. React 19
+      // hoists the <title>/<meta> elements rendered by <MetaTags> into <head>,
+      // so description/OG tags update on soft navigation, not just the title.
+      const nextMeta = (data.meta as MetaDescriptor[] | undefined) ?? [];
+      startTransition(() => setMeta(nextMeta));
     } catch (err) {
       console.error("[bractjs] loadRoute error:", err);
     } finally {
@@ -229,6 +242,7 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
   return (
     <RouterContext.Provider value={{ loaderData, actionData, params, pathname, manifest, currentModule, setRoute }}>
       <NavigationContext.Provider value={{ state: navState, navigate, submit }}>
+        <MetaTags meta={meta} />
         {children}
       </NavigationContext.Provider>
     </RouterContext.Provider>

package/src/client/components/Form.tsx

@@ -1,6 +1,7 @@
 import { useContext, type FormEvent, type ReactNode, type FormHTMLAttributes } from "react";
 import { RouterContext, NavigationContext } from "../router.tsx";
 import { reloadLoaders } from "../form-utils.ts";
+import { toSamePath } from "../nav-utils.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -49,8 +50,16 @@ export function Form({ method = "post", action, children, ...rest }: FormProps)
       headers: { "X-BractJS-Action": "1" },
     });
 
+    // The action returned (or threw) a redirect. The browser auto-follows the
+    // 3xx, so `response.url` is the *absolute* final URL — normalize it to a
+    // same-origin path before handing it to the client router, which matches a
+    // route pattern against the pathname (an absolute URL wouldn't match). An
+    // off-origin final URL is NOT handed to the SPA router: fall back to a
+    // full-page navigation so we don't open-redirect through it.
     if (response.redirected) {
-      await navigate(response.url);
+      const to = toSamePath(response.url);
+      if (to) { await navigate(to); return; }
+      window.location.href = response.url;
       return;
     }
 

package/src/client/hooks/useFetcher.ts

@@ -1,4 +1,5 @@
 import { useState } from "react";
+import { toSamePath } from "../nav-utils.ts";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
@@ -100,7 +101,22 @@ export function useFetcher<T>(opts?: { stream?: boolean }): FetcherResult | Stre
         submitOpts.body instanceof FormData
           ? submitOpts.body
           : new URLSearchParams(submitOpts.body as Record<string, string>);
-      const res = await fetch(path, { method: submitOpts.method, body });
+      // Send the custom header so the server's CSRF gate accepts this
+      // same-origin mutation (browsers block it cross-origin without a CORS
+      // preflight). Without it every fetcher submit 403s.
+      const res = await fetch(path, {
+        method: submitOpts.method,
+        body,
+        headers: { "X-BractJS-Action": "1" },
+      });
+      // If the action redirected, do a real navigation rather than parsing the
+      // redirect target as JSON. Off-origin targets get a full-page nav so we
+      // never follow an attacker-controlled Location inside the SPA.
+      if (res.redirected) {
+        const to = toSamePath(res.url);
+        window.location.assign(to ?? res.url);
+        return;
+      }
       setData(await res.json());
     } finally {
       setState("idle");

package/src/client/nav-utils.ts

@@ -1,5 +1,27 @@
 import type { ServerManifest } from "../server/render.ts";
 
+// ── Redirect normalization ─────────────────────────────────────────────────
+
+/**
+ * Normalize a Location/redirect target to a same-origin path the client router
+ * can match. Returns an internal "/path?query#hash" for same-origin targets, or
+ * `null` for off-origin, protocol-relative, or malformed values — the caller
+ * MUST NOT feed a null result to the SPA router (an off-origin Location should
+ * trigger a full-page navigation instead, so the browser applies its own
+ * cross-origin protections). This is the client-side complement to the server's
+ * `sanitizeRedirect()`: it stops a soft-nav from silently following an
+ * attacker-controlled `Location` header.
+ */
+export function toSamePath(loc: string): string | null {
+  try {
+    const u = new URL(loc, window.location.href);
+    if (u.origin !== window.location.origin) return null;
+    return u.pathname + u.search + u.hash;
+  } catch {
+    return null;
+  }
+}
+
 // ── Pattern Matching ───────────────────────────────────────────────────────
 
 /**
@@ -21,15 +43,44 @@ function patternMatches(pathname: string, pattern: string): boolean {
   return p === pathSegs.length;
 }
 
+/**
+ * Specificity score for a matching pattern, used to pick the best match the
+ * same way the server's trie does: static > dynamic > catch-all. Higher wins.
+ * Object key order is not reliable for priority, so we must score, not
+ * first-match (otherwise `[...slug]` can shadow `_index` / static routes).
+ */
+function patternScore(pattern: string): number {
+  if (pattern === "") return 1_000_000; // index route — most specific for "/"
+  let score = 0;
+  for (const seg of pattern.split("/")) {
+    score *= 10;
+    if (seg.startsWith("[...") && seg.endsWith("]")) score += 1; // catch-all
+    else if (seg.startsWith("[") && seg.endsWith("]")) score += 2; // dynamic
+    else score += 3; // static
+  }
+  return score;
+}
+
 // ── Export ─────────────────────────────────────────────────────────────────
 
-/** Returns the manifest pattern key that matches pathname, or null. */
+/** Returns the highest-priority manifest pattern that matches pathname, or null. */
 export function matchPatternForPath(
   pathname: string,
   manifest: ServerManifest,
 ): string | null {
+  // Exact static match wins outright (most specific) — also a fast path.
+  const normalized = pathname.replace(/^\//, "");
+  if (normalized in manifest.routes) return normalized;
+
+  let best: string | null = null;
+  let bestScore = -1;
   for (const pattern of Object.keys(manifest.routes)) {
-    if (patternMatches(pathname, pattern)) return pattern;
+    if (!patternMatches(pathname, pattern)) continue;
+    const score = patternScore(pattern);
+    if (score > bestScore) {
+      best = pattern;
+      bestScore = score;
+    }
   }
-  return null;
+  return best;
 }

package/src/client/types.ts

@@ -1,4 +1,5 @@
 import type { ServerManifest } from "../server/render.ts";
+import type { MetaDescriptor } from "../shared/route-types.ts";
 
 // ── BractJSClientData ────────────────────────────────────────────────────
 
@@ -10,6 +11,8 @@ export interface BractJSClientData {
   manifest: ServerManifest;
   /** Path of the matched route file, used to pre-import the module before hydration. */
   routeFile?: string;
+  /** Merged meta descriptors for the current route — keeps <head> in sync. */
+  meta?: MetaDescriptor[];
 }
 
 // ── Window augmentation ────────────────────────────────────────────────────

package/src/config/load.ts

@@ -1,6 +1,54 @@
 import { resolve } from "node:path";
 import type { BractJSConfig } from "../server/serve.ts";
 
+/**
+ * Shallow shape check for a user-supplied config object. We don't validate
+ * exhaustively (plugins/adapters/hooks are opaque), but we catch the common
+ * mistakes early — a string `port`, a non-array `clientEnv`, etc. — so the
+ * failure surfaces here with a clear message instead of deep inside the build
+ * or the request path.
+ */
+export function validateUserConfig(cfg: unknown): Partial<BractJSConfig> {
+  if (cfg === null || typeof cfg !== "object" || Array.isArray(cfg)) {
+    throw new Error(
+      `bractjs.config: default export must be a config object, got ${
+        Array.isArray(cfg) ? "array" : typeof cfg
+      }`,
+    );
+  }
+  const c = cfg as Record<string, unknown>;
+
+  const check = (key: string, ok: boolean, expected: string): void => {
+    if (key in c && c[key] !== undefined && !ok) {
+      throw new Error(`bractjs.config: "${key}" must be ${expected}`);
+    }
+  };
+
+  check("port", typeof c.port === "number" && Number.isFinite(c.port), "a finite number");
+  check("appDir", typeof c.appDir === "string", "a string");
+  check("publicDir", typeof c.publicDir === "string", "a string");
+  check("buildDir", typeof c.buildDir === "string", "a string");
+  check("imageCacheDir", typeof c.imageCacheDir === "string", "a string");
+  check("minify", typeof c.minify === "boolean", "a boolean");
+  check(
+    "sourcemap",
+    typeof c.sourcemap === "string" &&
+      ["none", "linked", "inline", "external"].includes(c.sourcemap as string),
+    'one of "none" | "linked" | "inline" | "external"',
+  );
+  check(
+    "clientEnv",
+    Array.isArray(c.clientEnv) && c.clientEnv.every((k) => typeof k === "string"),
+    "an array of strings",
+  );
+  check("plugins", Array.isArray(c.plugins), "an array of Bun plugins");
+  check("onStart", typeof c.onStart === "function", "a function");
+  check("onShutdown", typeof c.onShutdown === "function", "a function");
+  check("onError", typeof c.onError === "function", "a function");
+
+  return c as Partial<BractJSConfig>;
+}
+
 /**
  * Load `bractjs.config.ts` (or `.js`) from the user's cwd if present.
  * Returns an empty object when no file exists — callers fall back to defaults.
@@ -10,8 +58,8 @@ export async function loadUserConfig(): Promise<Partial<BractJSConfig>> {
     const path = resolve(process.cwd(), name);
     if (!(await Bun.file(path).exists())) continue;
     const mod = await import(path);
-    const cfg = (mod.default ?? mod) as Partial<BractJSConfig>;
-    return cfg ?? {};
+    const cfg = mod.default ?? mod;
+    return validateUserConfig(cfg ?? {});
   }
   return {};
 }

package/src/dev/devtools.ts

@@ -25,49 +25,68 @@ declare global {
 }
 
 const PANEL_ID = "bractjs-devtools-panel";
+const REFRESH_MS = 1000;
+
+function readState(): DevtoolsState {
+  return window.__BRACTJS_DEVTOOLS__ ?? {
+    route: null,
+    loaderData: {},
+    navState: "idle",
+    cacheEntries: [],
+    beforeLoadTrace: [],
+  };
+}
 
 class BractJSDevtools extends HTMLElement {
   private open = false;
   private panel: HTMLDivElement | null = null;
+  private refreshTimer: ReturnType<typeof setInterval> | null = null;
+  private readonly handleKeydown = (e: KeyboardEvent) => {
+    if (e.ctrlKey && e.shiftKey && e.key === "B") {
+      e.preventDefault();
+      this.togglePanel();
+    }
+  };
 
   connectedCallback() {
     this.style.cssText = "position:fixed;bottom:0;right:0;z-index:2147483647;font-family:monospace;";
 
-    const toggle = document.createElement("button");
-    toggle.textContent = "⚡ BractJS";
-    toggle.style.cssText =
-      "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
-    toggle.onclick = () => this.togglePanel();
-    this.appendChild(toggle);
-
-    // Keyboard shortcut
-    document.addEventListener("keydown", (e) => {
-      if (e.ctrlKey && e.shiftKey && e.key === "B") {
-        e.preventDefault();
-        this.togglePanel();
-      }
-    });
+    if (!this.querySelector("button")) {
+      const toggle = document.createElement("button");
+      toggle.textContent = "⚡ BractJS";
+      toggle.style.cssText =
+        "background:#1e1e1e;color:#61dafb;border:none;padding:4px 10px;cursor:pointer;font-size:12px;";
+      toggle.onclick = () => this.togglePanel();
+      this.appendChild(toggle);
+    }
+
+    document.addEventListener("keydown", this.handleKeydown);
+  }
+
+  disconnectedCallback() {
+    document.removeEventListener("keydown", this.handleKeydown);
+    this.stopRefresh();
   }
 
   private togglePanel() {
-    if (this.panel) {
-      this.panel.remove();
-      this.panel = null;
+    if (this.open) {
       this.open = false;
-    } else {
-      this.open = true;
-      this.renderPanel();
+      this.stopRefresh();
+      if (this.panel) {
+        this.panel.remove();
+        this.panel = null;
+      }
+      return;
     }
+
+    this.open = true;
+    this.ensurePanel();
+    this.renderPanel();
+    this.startRefresh();
   }
 
-  private renderPanel() {
-    const state = window.__BRACTJS_DEVTOOLS__ ?? {
-      route: null,
-      loaderData: {},
-      navState: "idle",
-      cacheEntries: [],
-      beforeLoadTrace: [],
-    };
+  private ensurePanel() {
+    if (this.panel) return;
 
     const panel = document.createElement("div");
     panel.id = PANEL_ID;
@@ -75,6 +94,31 @@ class BractJSDevtools extends HTMLElement {
       "background:#1e1e1e;color:#ccc;width:480px;max-height:60vh;overflow:auto;" +
       "border-top:2px solid #61dafb;border-left:2px solid #61dafb;padding:12px;font-size:11px;";
 
+    this.panel = panel;
+    this.appendChild(panel);
+  }
+
+  private startRefresh() {
+    this.stopRefresh();
+    this.refreshTimer = setInterval(() => {
+      if (!this.open || !this.panel) return;
+      this.renderPanel();
+    }, REFRESH_MS);
+  }
+
+  private stopRefresh() {
+    if (this.refreshTimer) {
+      clearInterval(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+  }
+
+  private renderPanel() {
+    if (!this.panel) return;
+    const state = readState();
+    const panel = this.panel;
+    panel.replaceChildren();
+
     const header = document.createElement("div");
     header.style.cssText = "color:#61dafb;font-weight:bold;margin-bottom:8px;font-size:13px;";
     header.textContent = "BractJS DevTools";
@@ -94,17 +138,6 @@ class BractJSDevtools extends HTMLElement {
     if (state.beforeLoadTrace.length > 0) {
       this.section(panel, "beforeLoad trace", state.beforeLoadTrace.join("\n"));
     }
-
-    this.panel = panel;
-    this.appendChild(panel);
-
-    // Auto-refresh every second while open.
-    const timer = setInterval(() => {
-      if (!this.open) { clearInterval(timer); return; }
-      panel.remove();
-      this.panel = null;
-      this.renderPanel();
-    }, 1000);
   }
 
   private section(parent: HTMLElement, title: string, content: string) {

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

@@ -1,6 +1,6 @@
 import { resolve, join, sep } from "node:path";
 import { realpath } from "node:fs/promises";
-import { serverOnlyPlugin } from "../build/env-plugin.ts";
+import { serverModuleStubPlugin } from "../build/env-plugin.ts";
 import { createUseServerProxyPlugin } from "../build/directives.ts";
 
 /**
@@ -48,14 +48,16 @@ export async function handleHmrModuleRequest(
   // build uses. Without these, a route module that imports `*.server.ts` or
   // contains "use server" exports would have that server source compiled and
   // shipped to the browser as JavaScript over /_hmr/module — leaking
-  // credentials, DB code, etc. The serverOnlyPlugin hard-fails such imports
-  // and useServerProxyPlugin rewrites "use server" exports to fetch stubs.
+  // credentials, DB code, etc. The serverModuleStubPlugin replaces every
+  // `*.server.ts` export with an inert stub (zero server source reaches the
+  // client) and useServerProxyPlugin rewrites "use server" exports to fetch
+  // stubs.
   const result = await Bun.build({
     entrypoints: [fullPath],
     target: "browser",
     minify: false,
     sourcemap: "inline",
-    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(rootDir)],
+    plugins: [serverModuleStubPlugin, createUseServerProxyPlugin(rootDir)],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/rebuilder.ts

@@ -1,5 +1,8 @@
 import type { BractJSConfig } from "../server/serve.ts";
 import { createUseServerProxyPlugin } from "../build/directives.ts";
+import { serverModuleStubPlugin, clientEnvPlugin } from "../build/env-plugin.ts";
+import { cssModulesPlugin } from "../build/plugins/css-modules.ts";
+import { reactDedupePlugin } from "../build/react-dedupe.ts";
 import { scanRoutes } from "../server/scanner.ts";
 import { generateManifest, writeManifest } from "../build/manifest.ts";
 import { mkdir, rename, rm } from "node:fs/promises";
@@ -48,7 +51,19 @@ export async function rebuildClient(
       // structure. publicPath + ../ traversals produce wrong absolute URLs.
       minify: false,
       sourcemap: "inline",
-      plugins: [createUseServerProxyPlugin(appDir), ...(config?.plugins ?? [])],
+      // SECURITY: mirror the production client-bundle guard plugins
+      // (src/build/bundler.ts). Without `serverModuleStubPlugin` a route that
+      // imports a `*.server.ts` module would have that server source compiled
+      // and served to the browser over /build/client in dev; without
+      // `clientEnvPlugin` server env vars would leak the same way.
+      plugins: [
+        reactDedupePlugin(process.cwd()),
+        serverModuleStubPlugin,
+        createUseServerProxyPlugin(appDir),
+        clientEnvPlugin(config?.clientEnv ?? [], Bun.env as Record<string, string>),
+        cssModulesPlugin,
+        ...(config?.plugins ?? []),
+      ],
     });
   } finally {
     await rm(shimPath, { force: true });

package/src/dev/server.ts

@@ -34,6 +34,9 @@ export async function createDevServer(options?: DevServerOptions): Promise<DevSe
 
   const userConfig = options?.skipUserConfig ? {} : await loadUserConfig();
   const merged: Partial<BractJSConfig> = { ...userConfig, ...options?.config };
+  // Note: the `"use client"` SSR stub is installed by buildFetchHandler (it runs
+  // for any source-import path, dev or `bractjs start`), so no separate dev hook
+  // is needed here.
 
   const hmrPort = options?.hmrPort ?? 3001;
   const appPort = options?.port ?? merged.port ?? 3000;