@bractjs/bractjs 0.1.21 → 0.1.23

package/src/codegen/module-registry.ts

@@ -0,0 +1,312 @@
+import { join, resolve } from "node:path";
+import { scanRoutes, type RouteFile } from "../server/scanner.ts";
+
+// Codegen entry-points: `bun build --compile` can't statically trace
+// `Bun.Glob` scans or `import(absPath)` calls, so we materialise the route /
+// layout / action graph into static `import` statements at build time. The
+// emitted files live at `<appDir>/_generated/{routes,actions}.ts` and are
+// imported by the user-facing `app/server.ts` entrypoint.
+
+// ── Path safety ────────────────────────────────────────────────────────────
+
+// Allow ASCII filename characters, `/` for nested directories, and `[`/`]`
+// for file-based dynamic route syntax (`[id]`, `[...slug]`). All emit sites
+// wrap the path in JSON.stringify, but we still allowlist the charset as
+// defense-in-depth against a hostile filename containing a backtick, $, quote,
+// backslash, or whitespace breaking out of the generated literal. `..` as a
+// whole segment is rejected separately below (path-traversal guard).
+const SAFE_FILEPATH_RE = /^[A-Za-z0-9._\/\-\[\]]+$/;
+
+function assertSafeFilePath(filePath: string): void {
+  if (!SAFE_FILEPATH_RE.test(filePath)) {
+    throw new Error(`[bractjs] codegen: refusing to emit unsafe file path: ${JSON.stringify(filePath)}`);
+  }
+  if (filePath.split("/").includes("..")) {
+    throw new Error(`[bractjs] codegen: refusing to emit path with .. segment: ${JSON.stringify(filePath)}`);
+  }
+}
+
+// Derive a JS identifier from an arbitrary relative path. Any character outside
+// `[A-Za-z0-9_]` collapses to `_`. The leading digit (if any) gets an `_`
+// prefix. This is purely for variable naming in the generated source; the
+// authoritative key for the registry is the JSON-stringified relPath.
+function pathToIdent(prefix: string, relPath: string): string {
+  const safe = relPath.replace(/[^A-Za-z0-9_]/g, "_");
+  return /^[0-9]/.test(safe) ? `${prefix}__${safe}` : `${prefix}_${safe}`;
+}
+
+// ── Layout discovery ───────────────────────────────────────────────────────
+
+function layoutDirsForPattern(urlPattern: string): string[] {
+  if (urlPattern === "") return [];
+  const segments = urlPattern.split("/");
+  segments.pop();
+  const dirs: string[] = [];
+  for (let i = 1; i <= segments.length; i++) {
+    dirs.push(segments.slice(0, i).join("/"));
+  }
+  return dirs;
+}
+
+/**
+ * Find every `routes/<dir>/layout.tsx` (or `.ts`) that exists on disk for the
+ * given set of routes. Mirrors the runtime probe in `resolveLayoutChain` but
+ * runs once at codegen time so the generated registry is exhaustive.
+ */
+async function collectLayouts(appDir: string, routes: RouteFile[]): Promise<string[]> {
+  const layoutPaths = new Set<string>();
+  for (const route of routes) {
+    for (const dir of layoutDirsForPattern(route.urlPattern)) {
+      for (const ext of ["tsx", "ts"]) {
+        const rel = `routes/${dir}/layout.${ext}`;
+        const abs = resolve(join(appDir, rel));
+        if (await Bun.file(abs).exists()) {
+          layoutPaths.add(rel);
+        }
+      }
+    }
+  }
+  return [...layoutPaths].sort();
+}
+
+// ── Action discovery ───────────────────────────────────────────────────────
+
+const SERVER_DIRECTIVE_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
+
+function isEligibleActionPath(rel: string): boolean {
+  return (
+    rel.endsWith(".server.ts") ||
+    rel.endsWith(".server.tsx") ||
+    rel.startsWith("routes/") ||
+    rel.startsWith("routes\\")
+  );
+}
+
+async function collectActionFiles(appDir: string): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.{ts,tsx}");
+  const found: string[] = [];
+  for await (const rel of glob.scan(appDir)) {
+    if (!isEligibleActionPath(rel)) continue;
+    // Skip the codegen output directory itself.
+    if (rel.startsWith("_generated/")) continue;
+    const abs = resolve(join(appDir, rel));
+    let src: string;
+    try {
+      src = await Bun.file(abs).text();
+    } catch {
+      continue;
+    }
+    if (!SERVER_DIRECTIVE_RE.test(src)) continue;
+    // Normalise Windows separators to POSIX for the registry key.
+    found.push(rel.split("\\").join("/"));
+  }
+  return found.sort();
+}
+
+// ── Generators ─────────────────────────────────────────────────────────────
+
+const HEADER =
+  "// Generated by `bractjs codegen` — do not edit manually.\n" +
+  "// Static imports here let `bun build --compile` trace every route, layout,\n" +
+  "// and server-action module instead of relying on runtime fs scans.\n" +
+  "\n" +
+  "/* eslint-disable */\n";
+
+export interface RouteRegistryInput {
+  appDir: string;
+  routes: RouteFile[];
+  layoutRelPaths: string[]; // e.g. ["routes/blog/layout.tsx"]
+  hasRoot: boolean;         // true if appDir/root.tsx exists
+}
+
+export function generateRouteRegistry(input: RouteRegistryInput): string {
+  const { routes, layoutRelPaths, hasRoot } = input;
+
+  // ── Build the import statements ──
+  const imports: string[] = [];
+  const entries: string[] = [];
+
+  if (hasRoot) {
+    assertSafeFilePath("root.tsx");
+    const ident = pathToIdent("mod", "root_tsx");
+    imports.push(`import * as ${ident} from "../root.tsx";`);
+    entries.push(`  ${JSON.stringify("root.tsx")}: ${ident},`);
+  }
+
+  for (const rel of layoutRelPaths) {
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("mod", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  ${JSON.stringify(rel)}: ${ident},`);
+  }
+
+  for (const r of routes) {
+    const rel = r.filePath.split("\\").join("/");
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("mod", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  ${JSON.stringify(rel)}: ${ident},`);
+  }
+
+  // ── routeFiles array literal (mirrors scanRoutes output shape) ──
+  const routeFilesLines: string[] = [];
+  for (const r of routes) {
+    const rel = r.filePath.split("\\").join("/");
+    assertSafeFilePath(rel);
+    const segments = JSON.stringify(r.segments);
+    routeFilesLines.push(
+      `  { filePath: ${JSON.stringify(rel)}, urlPattern: ${JSON.stringify(r.urlPattern)}, segments: ${segments} },`,
+    );
+  }
+
+  return [
+    HEADER,
+    `import type { RouteFile } from "@bractjs/bractjs";`,
+    `import type { RouteModule } from "@bractjs/bractjs";`,
+    "",
+    imports.join("\n"),
+    "",
+    "// Modules keyed by appDir-relative path. The framework looks up route,",
+    "// layout, and root modules here at request time instead of doing a",
+    "// dynamic `import(absPath)` call that would fail in a compiled binary.",
+    "export const moduleRegistry: Record<string, RouteModule> = {",
+    entries.join("\n"),
+    "};",
+    "",
+    "export const routeFiles: RouteFile[] = [",
+    routeFilesLines.join("\n"),
+    "];",
+    "",
+  ].join("\n");
+}
+
+export interface ActionRegistryInput {
+  appDir: string;
+  actionRelPaths: string[];
+}
+
+export function generateActionRegistry(input: ActionRegistryInput): string {
+  const { actionRelPaths } = input;
+
+  const imports: string[] = [];
+  const entries: string[] = [];
+
+  for (const rel of actionRelPaths) {
+    assertSafeFilePath(rel);
+    const ident = pathToIdent("act", rel);
+    imports.push(`import * as ${ident} from ${JSON.stringify("../" + rel)};`);
+    entries.push(`  { relPath: ${JSON.stringify(rel)}, mod: ${ident} as Record<string, unknown> },`);
+  }
+
+  return [
+    HEADER,
+    imports.join("\n"),
+    "",
+    "// Server-action modules, statically imported so `bun build --compile`",
+    "// traces them. The framework iterates this list and registers each",
+    "// exported function under SHA-256(relPath + \"#\" + name) — identical to",
+    "// the ID the client proxy plugin embeds in the bundled JS.",
+    "export const actionModules: Array<{ relPath: string; mod: Record<string, unknown> }> = [",
+    entries.join("\n"),
+    "];",
+    "",
+  ].join("\n");
+}
+
+// ── Manifest codegen ───────────────────────────────────────────────────────
+
+/**
+ * Shape produced by `src/build/manifest.ts` (`RouteManifest`). Re-typed here
+ * so the codegen module stays decoupled from the build pipeline.
+ */
+interface DiskManifest {
+  version?: number;
+  mode?: string;
+  clientEntry: string;
+  rootChunk?: string;
+  routes: Record<string, { chunk: string; pattern: string }>;
+}
+
+/**
+ * Convert the disk-format manifest (RouteManifest) into a TypeScript module
+ * exporting a `ServerManifest` constant. This decouples the compiled-binary
+ * server entry from the disk manifest — at startup it imports the constant
+ * instead of reading `build/route-manifest.json`.
+ */
+export function generateManifestModule(disk: DiskManifest): string {
+  // Mirror the RouteManifest → ServerManifest projection in serve.ts so the
+  // compiled binary sees the same shape `buildFetchHandler` would have built.
+  const projectedRoutes: Record<string, { file: string; chunk: string }> = {};
+  for (const [pat, entry] of Object.entries(disk.routes ?? {})) {
+    projectedRoutes[pat] = { file: entry.chunk, chunk: entry.chunk };
+  }
+  const projected = {
+    clientEntry: disk.clientEntry,
+    rootChunk: disk.rootChunk,
+    routes: projectedRoutes,
+  };
+  // JSON.stringify is safe for embedding — all strings get properly escaped.
+  // No template literals or backtick interpolation can leak through.
+  return [
+    HEADER,
+    `import type { ServerManifest } from "@bractjs/bractjs";`,
+    "",
+    "// Snapshot of build/route-manifest.json, frozen into the binary so the",
+    "// server never needs to read it from disk at startup.",
+    `export const manifest: ServerManifest = ${JSON.stringify(projected, null, 2)};`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * Read `<buildDir>/route-manifest.json` and write
+ * `<appDir>/_generated/manifest.ts`. Must run AFTER the client `Bun.build()`
+ * step — chunk filenames are content-hashed and not known until then.
+ */
+export async function writeManifestModule(
+  appDir: string,
+  buildDir: string,
+): Promise<string> {
+  const absAppDir = resolve(appDir);
+  const absBuildDir = resolve(buildDir);
+  const src = join(absBuildDir, "route-manifest.json");
+  const file = Bun.file(src);
+  if (!(await file.exists())) {
+    throw new Error(
+      `[bractjs] manifest codegen: ${src} not found. Run the client build before manifest codegen.`,
+    );
+  }
+  const disk = (await file.json()) as DiskManifest;
+  const out = join(absAppDir, "_generated", "manifest.ts");
+  await Bun.write(out, generateManifestModule(disk));
+  return out;
+}
+
+// ── Driver ─────────────────────────────────────────────────────────────────
+
+export interface CodegenResult {
+  routesPath: string;
+  actionsPath: string;
+}
+
+export async function writeModuleRegistries(appDir: string): Promise<CodegenResult> {
+  const absAppDir = resolve(appDir);
+  const routes = await scanRoutes(absAppDir);
+  const layoutRelPaths = await collectLayouts(absAppDir, routes);
+  const hasRoot =
+    (await Bun.file(resolve(join(absAppDir, "root.tsx"))).exists()) ||
+    (await Bun.file(resolve(join(absAppDir, "root.ts"))).exists());
+  const actionRelPaths = await collectActionFiles(absAppDir);
+
+  const routesSrc = generateRouteRegistry({ appDir: absAppDir, routes, layoutRelPaths, hasRoot });
+  const actionsSrc = generateActionRegistry({ appDir: absAppDir, actionRelPaths });
+
+  const outDir = resolve(join(absAppDir, "_generated"));
+  const routesPath = join(outDir, "routes.ts");
+  const actionsPath = join(outDir, "actions.ts");
+
+  await Bun.write(routesPath, routesSrc);
+  await Bun.write(actionsPath, actionsSrc);
+
+  return { routesPath, actionsPath };
+}

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

@@ -1,7 +1,7 @@
 import { resolve, join, sep } from "node:path";
 import { realpath } from "node:fs/promises";
 import { serverOnlyPlugin } from "../build/env-plugin.ts";
-import { useServerProxyPlugin } from "../build/directives.ts";
+import { createUseServerProxyPlugin } from "../build/directives.ts";
 
 /**
  * Dev-only HTTP handler for /_hmr/module?file=routes/about.tsx
@@ -55,7 +55,7 @@ export async function handleHmrModuleRequest(
     target: "browser",
     minify: false,
     sourcemap: "inline",
-    plugins: [serverOnlyPlugin, useServerProxyPlugin],
+    plugins: [serverOnlyPlugin, createUseServerProxyPlugin(rootDir)],
   });
 
   if (!result.success || result.outputs.length === 0) {

package/src/dev/rebuilder.ts

@@ -1,5 +1,5 @@
 import type { BractJSConfig } from "../server/serve.ts";
-import { useServerProxyPlugin } from "../build/directives.ts";
+import { createUseServerProxyPlugin } from "../build/directives.ts";
 import { scanRoutes } from "../server/scanner.ts";
 import { generateManifest, writeManifest } from "../build/manifest.ts";
 import { mkdir, rename, rm } from "node:fs/promises";
@@ -48,7 +48,7 @@ export async function rebuildClient(
       // structure. publicPath + ../ traversals produce wrong absolute URLs.
       minify: false,
       sourcemap: "inline",
-      plugins: [useServerProxyPlugin, ...(config?.plugins ?? [])],
+      plugins: [createUseServerProxyPlugin(appDir), ...(config?.plugins ?? [])],
     });
   } finally {
     await rm(shimPath, { force: true });

package/src/dev/server.ts

@@ -7,51 +7,88 @@ import { filePathToPattern } from "../server/scanner.ts";
 import { basename, extname } from "node:path";
 import type { LifecycleHooks } from "../server/lifecycle.ts";
 import { loadUserConfig } from "../config/load.ts";
+import type { BractJSConfig } from "../server/serve.ts";
 
-// Must precede any user-code import so SSR-time isDevRuntime() checks
-// (e.g. inside <LiveReload>) observe the dev mode.
-setRuntimeMode("dev");
+export interface DevServerOptions {
+  /** HTTP port for the app server. Default: config.port ?? 3000. */
+  port?: number;
+  /** WebSocket port for HMR. Default: 3001. */
+  hmrPort?: number;
+  /** Merged over values from bractjs.config.ts. */
+  config?: Partial<BractJSConfig>;
+  /**
+   * Skip loading bractjs.config.ts from cwd.
+   * Useful when the caller supplies the full config via the `config` option.
+   */
+  skipUserConfig?: boolean;
+}
+
+export interface DevServer {
+  stop(): void;
+}
 
-const userConfig = await loadUserConfig();
+export async function createDevServer(options?: DevServerOptions): Promise<DevServer> {
+  // Must precede any user-code import so SSR-time isDevRuntime() checks
+  // (e.g. inside <LiveReload>) observe the dev mode.
+  setRuntimeMode("dev");
 
-const hmr = createHmrServer(3001);
+  const userConfig = options?.skipUserConfig ? {} : await loadUserConfig();
+  const merged: Partial<BractJSConfig> = { ...userConfig, ...options?.config };
 
-// Build client bundle before the HTTP server starts accepting requests
-const { duration: initialMs } = await rebuildClient(userConfig);
-console.log(`[bractjs] initial client build in ${initialMs}ms`);
+  const hmrPort = options?.hmrPort ?? 3001;
+  const appPort = options?.port ?? merged.port ?? 3000;
 
-// Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
-let lifecycle: LifecycleHooks = {};
-try {
-  const lifecyclePath = `${process.cwd()}/app/lifecycle.ts`;
-  const mod = await import(lifecyclePath);
-  if (mod.default) lifecycle = mod.default;
-} catch {
-  // No lifecycle file — that's fine
-}
+  const hmr = createHmrServer(hmrPort);
 
-createServer({ port: 3000, ...userConfig, ...lifecycle });
-
-watchApp(userConfig.appDir ?? "./app", async (file) => {
-  const { duration } = await rebuildClient(userConfig);
-
-  // Route files (not layout): do a fine-grained module swap without full reload.
-  // Root, layouts, and other files: fall back to full page reload.
-  const isRoute =
-    file.startsWith("routes/") &&
-    !file.endsWith("layout.tsx") &&
-    !file.endsWith("layout.ts");
-
-  if (isRoute) {
-    const pattern = filePathToPattern(file);
-    // Chunk URL = same basename as route file; splitting build puts it in build/client/
-    const chunkUrl = `/build/client/${basename(file, extname(file))}.js`;
-    hmr.broadcast({ type: "hmr:route", pattern, chunkUrl, file, duration });
-    console.log(`✓ ${file} → module swap (pattern="${pattern}") in ${duration}ms`);
-  } else {
-    hmr.broadcast({ type: "hmr:reload", file, duration });
-    console.log(`✓ ${file} → full reload in ${duration}ms`);
+  // Build client bundle before the HTTP server starts accepting requests
+  const { duration: initialMs } = await rebuildClient(merged);
+  console.log(`[bractjs] initial client build in ${initialMs}ms`);
+
+  // Load user lifecycle hooks if defined (e.g. app/lifecycle.ts)
+  let lifecycle: LifecycleHooks = {};
+  try {
+    const lifecyclePath = `${process.cwd()}/app/lifecycle.ts`;
+    const mod = await import(lifecyclePath);
+    if (mod.default) lifecycle = mod.default;
+  } catch {
+    // No lifecycle file — that's fine
   }
-});
 
-console.log("BractJS dev server on http://localhost:3000");
+  const srv = createServer({ port: appPort, ...merged, ...lifecycle });
+
+  watchApp(merged.appDir ?? "./app", async (file) => {
+    const { duration } = await rebuildClient(merged);
+
+    // Route files (not layout): do a fine-grained module swap without full reload.
+    // Root, layouts, and other files: fall back to full page reload.
+    const isRoute =
+      file.startsWith("routes/") &&
+      !file.endsWith("layout.tsx") &&
+      !file.endsWith("layout.ts");
+
+    if (isRoute) {
+      const pattern = filePathToPattern(file);
+      // Chunk URL = same basename as route file; splitting build puts it in build/client/
+      const chunkUrl = `/build/client/${basename(file, extname(file))}.js`;
+      hmr.broadcast({ type: "hmr:route", pattern, chunkUrl, file, duration });
+      console.log(`✓ ${file} → module swap (pattern="${pattern}") in ${duration}ms`);
+    } else {
+      hmr.broadcast({ type: "hmr:reload", file, duration });
+      console.log(`✓ ${file} → full reload in ${duration}ms`);
+    }
+  });
+
+  console.log(`BractJS dev server on http://localhost:${appPort}`);
+
+  return {
+    stop() {
+      srv.stop();
+      hmr.stop();
+    },
+  };
+}
+
+// Preserve direct-run behavior: bun run src/dev/server.ts
+if (import.meta.main) {
+  await createDevServer();
+}

package/src/index.ts

@@ -14,7 +14,36 @@ export { BunAdapter } from "./server/adapter.ts";
 export { createCloudflareAdapter, makeCloudflareHandler } from "./adapters/cloudflare.ts";
 
 // Build plugins
+//
+// These plugins are REQUIRED when users compose their own `Bun.build` call
+// (e.g. native `bun build --compile` or a custom client bundle step). Missing
+// any of them breaks security or runtime behaviour:
+//
+// - `useClientStubPlugin` (server bundle): replaces "use client" modules with
+//   null stubs. Without it, the server binary crashes when React tries to
+//   call browser-only hooks/APIs.
+// - `createUseServerProxyPlugin(appDir)` (client bundle): replaces
+//   "use server" exports with fetch proxies. Without it, server-action
+//   bodies — including DB queries and secrets — ship inside the browser JS.
+// - `serverOnlyPlugin` (client bundle): hard-fails imports of `*.server.ts`
+//   files so server-only code can never be tree-walked into the client bundle.
+// - `clientEnvPlugin(allowedKeys, env)` (client bundle): allowlists which
+//   `process.env.*` references survive into the browser bundle.
+// - `cssModulesPlugin` (client bundle): handles `*.module.css` imports.
 export { cssModulesPlugin, transformCssModule } from "./build/plugins/css-modules.ts";
+export { useClientStubPlugin, createUseServerProxyPlugin, useServerProxyPlugin } from "./build/directives.ts";
+export { serverOnlyPlugin, clientEnvPlugin } from "./build/env-plugin.ts";
+
+// Module-registry codegen (drives `bun build --compile` workflow)
+export {
+  writeModuleRegistries,
+  writeManifestModule,
+  generateRouteRegistry,
+  generateActionRegistry,
+  generateManifestModule,
+} from "./codegen/module-registry.ts";
+export type { CodegenResult } from "./codegen/module-registry.ts";
+export type { ModuleRegistry } from "./server/layout.ts";
 
 // Client RPC
 export { createClient } from "./client/rpc.ts";
@@ -34,6 +63,7 @@ export type {
   RouteModule,
   RouteDefinition,
 } from "./shared/route-types.ts";
+export type { RouteFile, Segment } from "./server/scanner.ts";
 
 export { BractJSError, HttpError, isRedirect, isHttpError, isBractJSError } from "./shared/errors.ts";
 export { Deferred, defer, isDeferred } from "./shared/deferred.ts";
@@ -78,3 +108,10 @@ export { useLocalizedLink } from "./client/hooks/useLocalizedLink.ts";
 // i18n utilities (server-side)
 export { wrapRoutesWithLocale, stripLocale, localizedDataPath } from "./server/i18n.ts";
 export type { I18nConfig } from "./server/serve.ts";
+
+// Programmatic API — importable alternatives to the CLI commands
+export { createDevServer } from "./dev/server.ts";
+export type { DevServerOptions, DevServer } from "./dev/server.ts";
+export { runBuild } from "./build/bundler.ts";
+export type { BuildConfig } from "./build/bundler.ts";
+export { loadUserConfig } from "./config/load.ts";

package/src/server/action-registry.ts

@@ -1,4 +1,4 @@
-import { join } from "node:path";
+import { join, relative, resolve, isAbsolute } from "node:path";
 
 // Anchored at start-of-file. Allow whitespace and line/block comments before
 // the "use server" string literal. This prevents false matches from a "use
@@ -6,8 +6,12 @@ import { join } from "node:path";
 const SERVER_RE = /^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*["']use server["']/;
 const registry = new Map<string, (...args: unknown[]) => Promise<unknown>>();
 
-async function computeId(filePath: string, name: string): Promise<string> {
-  const raw = new TextEncoder().encode(filePath + "#" + name);
+/**
+ * Hash key for an action — must use the same string the client-side proxy
+ * plugin hashes (`pathKey + "#" + name`). Mismatch → `/_action?id=...` 404.
+ */
+async function computeId(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"))
@@ -15,6 +19,18 @@ async function computeId(filePath: string, name: string): Promise<string> {
     .slice(0, 16);
 }
 
+/**
+ * Convert an absolute file path to the appDir-relative key used for hashing.
+ * Matches `pathKeyForAction` in `src/build/directives.ts`. Files outside
+ * appDir keep their absolute path so external imports stay hashable but
+ * distinct from in-tree files.
+ */
+function pathKeyForAction(absPath: string, appDir: string): string {
+  const absAppDir = isAbsolute(appDir) ? appDir : resolve(appDir);
+  const rel = relative(absAppDir, absPath);
+  return rel.startsWith("..") ? absPath : rel;
+}
+
 export function resolveAction(id: string): ((...args: unknown[]) => Promise<unknown>) | null {
   return registry.get(id) ?? null;
 }
@@ -47,7 +63,28 @@ export async function loadServerActions(appDir: string): Promise<void> {
 
     for (const [name, val] of Object.entries(mod)) {
       if (typeof val !== "function") continue;
-      const id = await computeId(filePath, name);
+      const id = await computeId(pathKeyForAction(filePath, appDir), name);
+      registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
+    }
+  }
+}
+
+/**
+ * Registry-driven counterpart to `loadServerActions`. Skips the filesystem
+ * scan and dynamic imports — every entry was already statically imported by
+ * `_generated/actions.ts`, so we just iterate and register.
+ *
+ * Each entry's `relPath` MUST be appDir-relative (matches what
+ * `createUseServerProxyPlugin(appDir)` hashed during the client build).
+ * Mismatched relPaths produce silent `/_action?id=...` 404s.
+ */
+export async function loadServerActionsFromRegistry(
+  entries: Array<{ relPath: string; mod: Record<string, unknown> }>,
+): Promise<void> {
+  for (const { relPath, mod } of entries) {
+    for (const [name, val] of Object.entries(mod)) {
+      if (typeof val !== "function") continue;
+      const id = await computeId(relPath, name);
       registry.set(id, val as (...args: unknown[]) => Promise<unknown>);
     }
   }