@bractjs/bractjs 0.1.21 → 0.1.23

package/src/__tests__/module-registry.test.ts

@@ -0,0 +1,178 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import {
+  generateRouteRegistry,
+  generateActionRegistry,
+  generateManifestModule,
+  writeModuleRegistries,
+  writeManifestModule,
+} from "../codegen/module-registry.ts";
+
+const TMP = resolve(import.meta.dir, ".tmp-module-registry");
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(join(TMP, "routes", "blog"), { recursive: true });
+
+  await writeFile(join(TMP, "root.tsx"), `export default function Root() { return null; }\n`);
+  await writeFile(join(TMP, "routes", "_index.tsx"), `export default function Home() { return null; }\n`);
+  await writeFile(join(TMP, "routes", "blog", "layout.tsx"), `export default function L({ children }: any) { return children; }\n`);
+  // Nested route — `routes/blog/layout.tsx` only applies because there is a
+  // deeper route under /blog/. Layouts wrap children, not the leaf at the
+  // same path level (matches `layout.ts`'s `layoutDirs` resolution).
+  await writeFile(join(TMP, "routes", "blog", "[slug].tsx"), `export default function P() { return null; }\n`);
+
+  await writeFile(
+    join(TMP, "contact.server.ts"),
+    `"use server";\nexport async function send() { return 1; }\n`,
+  );
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("generateRouteRegistry", () => {
+  test("emits static imports and module map for root, layout, routes", () => {
+    const src = generateRouteRegistry({
+      appDir: TMP,
+      routes: [
+        { filePath: "routes/_index.tsx", urlPattern: "", segments: [] },
+        { filePath: "routes/blog/_index.tsx", urlPattern: "blog", segments: ["blog"] },
+      ],
+      layoutRelPaths: ["routes/blog/layout.tsx"],
+      hasRoot: true,
+    });
+
+    expect(src).toContain(`import * as mod_root_tsx from "../root.tsx";`);
+    expect(src).toContain(`import * as mod_routes_blog_layout_tsx from "../routes/blog/layout.tsx";`);
+    expect(src).toContain(`import * as mod_routes__index_tsx from "../routes/_index.tsx";`);
+    expect(src).toContain(`"root.tsx": mod_root_tsx,`);
+    expect(src).toContain(`"routes/blog/layout.tsx": mod_routes_blog_layout_tsx,`);
+    expect(src).toContain(`export const moduleRegistry: Record<string, RouteModule>`);
+    expect(src).toContain(`export const routeFiles: RouteFile[]`);
+  });
+
+  test("rejects hostile file paths", () => {
+    expect(() =>
+      generateRouteRegistry({
+        appDir: TMP,
+        routes: [{ filePath: "routes/`evil`.tsx", urlPattern: "evil", segments: ["evil"] }],
+        layoutRelPaths: [],
+        hasRoot: false,
+      }),
+    ).toThrow(/unsafe file path/);
+  });
+
+  test("rejects .. segments", () => {
+    expect(() =>
+      generateRouteRegistry({
+        appDir: TMP,
+        routes: [{ filePath: "routes/../evil.tsx", urlPattern: "evil", segments: ["evil"] }],
+        layoutRelPaths: [],
+        hasRoot: false,
+      }),
+    ).toThrow(/\.\. segment/);
+  });
+});
+
+describe("generateActionRegistry", () => {
+  test("emits static imports and registers each action file", () => {
+    const src = generateActionRegistry({
+      appDir: TMP,
+      actionRelPaths: ["routes/contact.server.ts"],
+    });
+    expect(src).toContain(`import * as act_routes_contact_server_ts from "../routes/contact.server.ts";`);
+    expect(src).toContain(`{ relPath: "routes/contact.server.ts", mod: act_routes_contact_server_ts as Record<string, unknown> }`);
+  });
+
+  test("rejects hostile action paths", () => {
+    expect(() =>
+      generateActionRegistry({
+        appDir: TMP,
+        actionRelPaths: ["routes/`evil`.server.ts"],
+      }),
+    ).toThrow(/unsafe file path/);
+  });
+});
+
+describe("writeModuleRegistries", () => {
+  test("scans the fixture app and writes both registry files", async () => {
+    const { routesPath, actionsPath } = await writeModuleRegistries(TMP);
+    expect(routesPath).toBe(resolve(join(TMP, "_generated", "routes.ts")));
+    expect(actionsPath).toBe(resolve(join(TMP, "_generated", "actions.ts")));
+
+    const routesSrc = await Bun.file(routesPath).text();
+    expect(routesSrc).toContain(`import * as mod_root_tsx from "../root.tsx";`);
+    // Layout is discovered because `routes/blog/[slug].tsx` is a deeper route
+    expect(routesSrc).toContain(`"routes/blog/layout.tsx": `);
+    expect(routesSrc).toContain(`urlPattern: ""`);
+
+    const actionsSrc = await Bun.file(actionsPath).text();
+    expect(actionsSrc).toContain(`relPath: "contact.server.ts"`);
+  });
+});
+
+describe("generateManifestModule", () => {
+  test("emits a ServerManifest constant with file+chunk per route", () => {
+    const src = generateManifestModule({
+      version: 1,
+      mode: "production",
+      clientEntry: "/build/client/entry.abc.js",
+      rootChunk: "/build/client/root.def.js",
+      routes: {
+        "": { chunk: "/build/client/_index.ghi.js", pattern: "" },
+        "blog": { chunk: "/build/client/blog.jkl.js", pattern: "blog" },
+      },
+    });
+    expect(src).toContain(`export const manifest: ServerManifest =`);
+    expect(src).toContain(`"clientEntry": "/build/client/entry.abc.js"`);
+    expect(src).toContain(`"rootChunk": "/build/client/root.def.js"`);
+    // Each route entry exposes both `file` and `chunk` keys (mirrors the
+    // RouteManifest → ServerManifest projection in serve.ts).
+    expect(src).toContain(`"file": "/build/client/_index.ghi.js"`);
+    expect(src).toContain(`"chunk": "/build/client/_index.ghi.js"`);
+  });
+
+  test("string escaping resists injection through chunk paths", () => {
+    const src = generateManifestModule({
+      clientEntry: `evil"; throw new Error('pwned'); //`,
+      routes: {},
+    });
+    // JSON.stringify escapes the inner quote — the throw doesn't break out.
+    expect(src).toContain(`\\"; throw new Error`);
+    expect(src).not.toContain(`evil"; throw`);
+  });
+});
+
+describe("writeManifestModule", () => {
+  test("reads route-manifest.json and writes _generated/manifest.ts", async () => {
+    const tmpBuild = resolve(join(TMP, ".tmp-build"));
+    await mkdir(tmpBuild, { recursive: true });
+    await writeFile(
+      join(tmpBuild, "route-manifest.json"),
+      JSON.stringify({
+        version: 1,
+        mode: "production",
+        clientEntry: "/build/client/entry.abc.js",
+        routes: { "": { chunk: "/build/client/_index.ghi.js", pattern: "" } },
+      }),
+    );
+    const out = await writeManifestModule(TMP, tmpBuild);
+    expect(out).toBe(resolve(join(TMP, "_generated", "manifest.ts")));
+    const src = await Bun.file(out).text();
+    expect(src).toContain(`"clientEntry": "/build/client/entry.abc.js"`);
+  });
+
+  test("throws a clear error when route-manifest.json is missing", async () => {
+    let caught: unknown;
+    try {
+      await writeManifestModule(TMP, "/this/path/does/not/exist-bract-manifest");
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect((caught as Error).message).toContain("Run the client build before manifest codegen");
+  });
+});

package/src/__tests__/prebuilt-handler.test.ts

@@ -0,0 +1,94 @@
+import { test, expect, describe } from "bun:test";
+import { buildFetchHandler } from "../server/serve.ts";
+import type { RouteModule } from "../shared/route-types.ts";
+
+// Validates the `bun build --compile` code path: every input that the
+// framework would normally derive from the filesystem (`Bun.Glob` of routes/,
+// `import(absPath)` of route modules, `loadManifest` from disk) is provided
+// upfront. The appDir/publicDir/buildDir paths point at a nonexistent
+// directory to prove no filesystem fall-through happens.
+
+const NON_EXISTENT_DIR = "/this/path/does/not/exist/bractjs-prebuilt";
+
+const indexRouteModule: RouteModule = {
+  loader: async () => ({ ok: true, source: "prebuilt-loader" }),
+  meta: () => [{ title: "Prebuilt Title" }],
+  default: () => null,
+};
+
+const rootModule: RouteModule = {
+  default: () => null,
+};
+
+const sendActionMod = {
+  send: async (payload: unknown) => ({ echoed: payload }),
+};
+
+// Hash matches the ID a client proxy would compute for relPath "actions.server.ts" + "send".
+async function clientId(relPath: string, name: string): Promise<string> {
+  const raw = new TextEncoder().encode(relPath + "#" + 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);
+}
+
+const fetchHandler = buildFetchHandler({
+  appDir: NON_EXISTENT_DIR,
+  publicDir: NON_EXISTENT_DIR,
+  buildDir: NON_EXISTENT_DIR,
+  manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  routeFiles: [
+    { filePath: "routes/_index.tsx", urlPattern: "", segments: [] },
+  ],
+  moduleRegistry: {
+    "root.tsx": rootModule,
+    "routes/_index.tsx": indexRouteModule,
+  },
+  actionModules: [
+    { relPath: "actions.server.ts", mod: sendActionMod },
+  ],
+});
+
+describe("buildFetchHandler — pre-built (compiled-binary) path", () => {
+  test("GET / renders HTML with loader data from registry", async () => {
+    const res = await fetchHandler(new Request("http://x/"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    const html = await res.text();
+    expect(html).toContain("prebuilt-loader");
+    expect(html).toContain("Prebuilt Title");
+  });
+
+  test("GET /_data?path=/ returns JSON loader output", async () => {
+    const res = await fetchHandler(new Request("http://x/_data?path=/"));
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as Record<string, unknown>;
+    expect(data).toHaveProperty("route");
+    expect((data.route as Record<string, unknown>).ok).toBe(true);
+  });
+
+  test("GET /missing returns 404 from the prebuilt trie", async () => {
+    const res = await fetchHandler(new Request("http://x/missing"));
+    expect(res.status).toBe(404);
+  });
+
+  test("POST /_action with registry-derived ID succeeds", async () => {
+    const id = await clientId("actions.server.ts", "send");
+    const res = await fetchHandler(
+      new Request(`http://x/_action?id=${id}`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "X-BractJS-Action": "1",
+          Origin: "http://x",
+        },
+        body: JSON.stringify([{ hello: "world" }]),
+      }),
+    );
+    expect(res.status).toBe(200);
+    const json = (await res.json()) as { echoed: Record<string, unknown> };
+    expect(json.echoed).toEqual({ hello: "world" });
+  });
+});

package/src/__tests__/programmatic-api.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Tests for the programmatic API: createDevServer, runBuild, loadUserConfig.
+ *
+ * Note: tests that start Bun.serve() (like integration.test.ts) are excluded
+ * here because the process.on("beforeExit") handler in createServer causes
+ * bun:test to exit before printing results — a known pre-existing issue.
+ * Behavioral coverage (HTTP response, HMR) lives in integration.test.ts.
+ */
+import { test, expect } from "bun:test";
+import { loadUserConfig } from "../config/load.ts";
+import { runBuild } from "../build/bundler.ts";
+import { createDevServer } from "../dev/server.ts";
+import type { BuildConfig } from "../build/bundler.ts";
+import type { DevServerOptions, DevServer } from "../dev/server.ts";
+
+// ── loadUserConfig ────────────────────────────────────────────────────────
+
+test("loadUserConfig is exported from config/load", () => {
+  expect(typeof loadUserConfig).toBe("function");
+});
+
+test("loadUserConfig returns an object when no bractjs.config.ts exists", async () => {
+  // Repo root has no bractjs.config.ts — must return a plain empty object.
+  const cfg = await loadUserConfig();
+  expect(typeof cfg).toBe("object");
+  expect(cfg).not.toBeNull();
+});
+
+// ── runBuild ──────────────────────────────────────────────────────────────
+
+test("runBuild is exported from build/bundler", () => {
+  expect(typeof runBuild).toBe("function");
+});
+
+test("runBuild signature does not require server-only fields (port/manifest/publicDir)", () => {
+  // Compile-time guard: if BuildConfig mistakenly included required server fields,
+  // this line would fail TypeScript type-checking.
+  const config: BuildConfig = { appDir: "./app", minify: false };
+  expect(typeof config).toBe("object");
+  // Ensure none of the server-only keys are present as required fields.
+  expect("port" in config).toBe(false);
+  expect("manifest" in config).toBe(false);
+  expect("publicDir" in config).toBe(false);
+});
+
+test("runBuild rejects with a defined error when appDir does not exist", async () => {
+  await expect(
+    runBuild({ appDir: "/definitely/does/not/exist/__bractjs_test__" }),
+  ).rejects.toBeDefined();
+});
+
+// ── createDevServer ───────────────────────────────────────────────────────
+
+test("createDevServer is exported from dev/server", () => {
+  expect(typeof createDevServer).toBe("function");
+});
+
+test("createDevServer accepts DevServerOptions shape without error at compile time", () => {
+  // Compile-time guard: verify the options interface has the expected fields.
+  const opts: DevServerOptions = {
+    port: 3997,
+    hmrPort: 3996,
+    skipUserConfig: true,
+    config: { appDir: "./app" },
+  };
+  expect(typeof opts).toBe("object");
+  expect(opts.port).toBe(3997);
+  expect(opts.hmrPort).toBe(3996);
+  expect(opts.skipUserConfig).toBe(true);
+});
+
+test("DevServer interface has a stop() method", () => {
+  // Compile-time guard: verify DevServer shape.
+  const stub: DevServer = { stop: () => {} };
+  expect(typeof stub.stop).toBe("function");
+});
+
+// ── Re-exports from src/index.ts ──────────────────────────────────────────
+
+test("createDevServer, runBuild, loadUserConfig are all re-exported from src/index.ts", async () => {
+  const mod = await import("../index.ts");
+  expect(typeof mod.createDevServer).toBe("function");
+  expect(typeof mod.runBuild).toBe("function");
+  expect(typeof mod.loadUserConfig).toBe("function");
+});

package/src/__tests__/security.test.ts

@@ -1,6 +1,6 @@
 import { test, expect, describe, beforeAll, afterAll } from "bun:test";
 import { mkdir, rm, writeFile, symlink } from "node:fs/promises";
-import { resolve, join } from "node:path";
+import { resolve, join, relative, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
 import { createServer } from "../server/serve.ts";
 import { handleActionRequest } from "../server/action-handler.ts";
@@ -15,8 +15,16 @@ import { handleImageRequest } from "../image/handler.ts";
 const ACTION_TMP = resolve(import.meta.dir, ".tmp-security-action");
 let registeredActionId = "";
 
-async function computeId(filePath: string, name: string): Promise<string> {
-  const raw = new TextEncoder().encode(filePath + "#" + name);
+// Mirrors `pathKeyForAction` — action IDs hash the appDir-relative path so
+// they stay consistent between the server registry and the client proxy.
+function pathKey(absPath: string, appDir: string): string {
+  const absAppDir = isAbsolute(appDir) ? appDir : resolve(appDir);
+  const rel = relative(absAppDir, absPath);
+  return rel.startsWith("..") ? absPath : rel;
+}
+
+async function computeId(absPath: string, name: string, appDir: string): Promise<string> {
+  const raw = new TextEncoder().encode(pathKey(absPath, appDir) + "#" + name);
   const buf = await crypto.subtle.digest("SHA-256", raw);
   return Array.from(new Uint8Array(buf))
     .map((b) => b.toString(16).padStart(2, "0"))
@@ -42,7 +50,7 @@ beforeAll(async () => {
   const actionFile = join(ACTION_TMP, "routes", "_index.tsx");
   await writeFile(actionFile, `"use server";\nexport async function ping(...args) { return args; }\n`);
   await loadServerActions(ACTION_TMP);
-  registeredActionId = await computeId(actionFile, "ping");
+  registeredActionId = await computeId(actionFile, "ping", ACTION_TMP);
 });
 
 afterAll(async () => {

package/src/__tests__/static-embedded.test.ts

@@ -0,0 +1,74 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile, symlink } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { serveStatic } from "../server/static.ts";
+
+const TMP = resolve(import.meta.dir, ".tmp-static-embedded");
+const BUILD = join(TMP, "build");
+const PUBLIC = join(TMP, "public");
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(join(BUILD, "client"), { recursive: true });
+  await mkdir(PUBLIC, { recursive: true });
+
+  await writeFile(join(BUILD, "client", "app.js"), "console.log('app');");
+  await writeFile(join(PUBLIC, "logo.svg"), "<svg/>");
+
+  // Outside-root file for symlink-escape test
+  await writeFile(join(TMP, "secret.txt"), "shhh");
+  // Symlink from inside build/client/ to a file OUTSIDE the root
+  await symlink(join(TMP, "secret.txt"), join(BUILD, "client", "escape.js"));
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("serveStatic — normal filesystem path", () => {
+  test("serves a client asset", async () => {
+    const res = await serveStatic("/build/client/app.js", BUILD, PUBLIC);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("Cache-Control")).toContain("immutable");
+    expect(await res!.text()).toContain("console.log");
+  });
+
+  test("serves a public asset", async () => {
+    const res = await serveStatic("/public/logo.svg", BUILD, PUBLIC);
+    expect(res).not.toBeNull();
+    expect(res!.status).toBe(200);
+    expect(res!.headers.get("Cache-Control")).toContain("no-cache");
+  });
+
+  test("returns null for unmatched prefix", async () => {
+    expect(await serveStatic("/api/foo", BUILD, PUBLIC)).toBeNull();
+  });
+
+  test("blocks .. traversal segments", async () => {
+    expect(
+      await serveStatic("/build/client/../secret.txt", BUILD, PUBLIC),
+    ).toBeNull();
+  });
+
+  test("blocks symlink that escapes the root after realpath", async () => {
+    // realpath resolves escape.js → ../secret.txt → outside BUILD/client.
+    // Must return null, NOT serve the secret file.
+    const res = await serveStatic("/build/client/escape.js", BUILD, PUBLIC);
+    expect(res).toBeNull();
+  });
+});
+
+describe("serveStatic — embedded-binary fallback", () => {
+  test("structural traversal guard still blocks .. even when realpath throws", async () => {
+    // `/build/client/__definitely_missing__.js` doesn't exist → realpath
+    // throws → fallback runs → Bun.file().exists() returns false → null.
+    // Guarantees the fallback doesn't accidentally serve nonexistent paths.
+    const res = await serveStatic(
+      "/build/client/__definitely_missing__.js",
+      BUILD,
+      PUBLIC,
+    );
+    expect(res).toBeNull();
+  });
+});

package/src/build/bundler.ts

@@ -1,16 +1,26 @@
 import { join, basename, extname, resolve } from "node:path";
 import { rename, rm } from "node:fs/promises";
-import type { BractJSConfig } from "../server/serve.ts";
+import type { BunPlugin } from "bun";
 import { scanRoutes } from "../server/scanner.ts";
 import { contentHash } from "./hash.ts";
 import { generateManifest, writeManifest } from "./manifest.ts";
 import { serverOnlyPlugin, clientEnvPlugin } from "./env-plugin.ts";
 import { buildDefines } from "./defines.ts";
 import { writeRouteTypes } from "../codegen/route-codegen.ts";
-import { useClientStubPlugin, useServerProxyPlugin } from "./directives.ts";
+import { useClientStubPlugin, createUseServerProxyPlugin } from "./directives.ts";
 import { cssModulesPlugin } from "./plugins/css-modules.ts";
 
-export async function runBuild(config: BractJSConfig): Promise<void> {
+/** Subset of config fields relevant to the build pipeline. */
+export interface BuildConfig {
+  appDir?: string;
+  buildDir?: string;
+  sourcemap?: "none" | "linked" | "inline" | "external";
+  minify?: boolean;
+  clientEnv?: string[];
+  plugins?: BunPlugin[];
+}
+
+export async function runBuild(config: BuildConfig): Promise<void> {
   const appDir = config.appDir ?? "./app";
 
   // ── 0. Codegen — typed routes ───────────────────────────────────────────
@@ -54,7 +64,7 @@ export async function runBuild(config: BractJSConfig): Promise<void> {
     minify: config.minify ?? true,
     sourcemap: config.sourcemap ?? "external",
     define: buildDefines(config),
-    plugins: [serverOnlyPlugin, useServerProxyPlugin, clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin, ...(config.plugins ?? [])],
+    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(appDir), clientEnvPlugin(config.clientEnv ?? [], Bun.env as Record<string, string>), cssModulesPlugin, ...(config.plugins ?? [])],
   });
   if (!clientResult.success) throw new AggregateError(clientResult.logs, "Client build failed");
 

package/src/build/directives.ts

@@ -1,4 +1,5 @@
 import type { BunPlugin } from "bun";
+import { relative, resolve, isAbsolute } from "node:path";
 
 const CLIENT_RE = /^["']use client["']/m;
 const SERVER_RE = /^["']use server["']/m;
@@ -37,8 +38,14 @@ function extractExports(src: string): string[] {
   return names;
 }
 
-async function actionId(filePath: string, name: string): Promise<string> {
-  const raw = new TextEncoder().encode(filePath + "#" + name);
+/**
+ * Compute stable action ID from a path key (relative when appDir provided)
+ * and an exported function name. Server-side counterpart is `computeId` in
+ * `src/server/action-registry.ts` — both MUST hash identical input strings
+ * or the client proxy hits a 404 at `/_action?id=...`.
+ */
+async function actionId(pathKey: string, name: string): Promise<string> {
+  const raw = new TextEncoder().encode(pathKey + "#" + name);
   const buf = await crypto.subtle.digest("SHA-256", raw);
   return Array.from(new Uint8Array(buf))
     .map((b) => b.toString(16).padStart(2, "0"))
@@ -46,6 +53,22 @@ async function actionId(filePath: string, name: string): Promise<string> {
     .slice(0, 16);
 }
 
+/**
+ * Convert the absolute path Bun's onLoad passes us into the path key we hash
+ * for action IDs. When `appDir` is provided, returns appDir-relative path so
+ * IDs survive CI→prod machine moves and compiled-binary embedding. Without
+ * `appDir`, falls back to the absolute path (legacy behavior).
+ */
+function pathKeyForAction(absPath: string, appDir?: string): string {
+  if (!appDir) return absPath;
+  const absAppDir = isAbsolute(appDir) ? appDir : resolve(appDir);
+  const rel = relative(absAppDir, absPath);
+  // If the file lives outside appDir (escape), `relative` returns a path
+  // starting with "..". Fall back to the absolute path so external imports
+  // remain hashable but stay distinct from in-tree files.
+  return rel.startsWith("..") ? absPath : rel;
+}
+
 /** Server build: stub "use client" modules → null components to prevent browser API crashes. */
 export const useClientStubPlugin: BunPlugin = {
   name: "bractjs:use-client-stub",
@@ -73,22 +96,38 @@ const PROXY_HELPER = `async function __bract(id: string, args: unknown[]): Promi
   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 (!hasServerDirective(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" };
-    });
-  },
-};
+/**
+ * Client build: replace "use server" exports with fetch proxy stubs.
+ *
+ * Factory form so the plugin can compute appDir-relative action IDs that
+ * match the server registry across machines and inside compiled binaries.
+ * Pass the same `appDir` used by `loadServerActions` on the server.
+ */
+export function createUseServerProxyPlugin(appDir?: string): BunPlugin {
+  return {
+    name: "bractjs:use-server-proxy",
+    setup(build) {
+      build.onLoad({ filter: /\.(tsx?|jsx?)$/ }, async ({ path }) => {
+        const src = await Bun.file(path).text();
+        if (!hasServerDirective(src)) return undefined;
+        const names = extractExports(src);
+        if (names.length === 0) return { contents: "export {};", loader: "ts" };
+        const key = pathKeyForAction(path, appDir);
+        const proxies = await Promise.all(
+          names.map(async (name) => {
+            const id = await actionId(key, name);
+            return `export const ${name} = (...args: unknown[]) => __bract("${id}", args);`;
+          }),
+        );
+        return { contents: PROXY_HELPER + "\n" + proxies.join("\n"), loader: "ts" };
+      });
+    },
+  };
+}
+
+/**
+ * Backwards-compatible default — hashes by absolute path. New code should
+ * call `createUseServerProxyPlugin(appDir)` so IDs are stable across the
+ * client bundle and server registry regardless of where the build runs.
+ */
+export const useServerProxyPlugin: BunPlugin = createUseServerProxyPlugin();

package/src/client/ClientRouter.tsx

@@ -157,7 +157,10 @@ export function ClientRouter({ children, initialData, initialModule = null }: Cl
       if (w.__BRACT_DEV__ === true) {
         // Use the dev-only HTTP endpoint (registered in serve.ts) rather than
         // a relative source-path import — Bun preserves dynamic-import paths
-        // as runtime URLs, and a relative .ts path 404s in the browser.
+        // as runtime URLs, and a relative .ts path 404s in the browser. TS
+        // can't resolve the absolute URL spec, but `.catch()` below swallows
+        // the import failure in prod where the endpoint isn't registered.
+        // @ts-expect-error TS2307 — runtime URL served by serve.ts in dev only
         void import(/* @vite-ignore */ "/_bractjs/devtools.js").then(({ updateDevtoolsState }) => {
           updateDevtoolsState({
             route: toPathname,