@bractjs/bractjs 0.1.22 → 0.1.23

package/README.md

@@ -442,12 +442,13 @@ export const db = new Database(Bun.env.DATABASE_URL);
 
 ## Server Lifecycle Hooks
 
-Use `defineLifecycle()` in `app/lifecycle.ts` to run code when the server starts or shuts down. The shutdown hook runs on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, and uncaught exceptions), so database connections are always closed cleanly.
+Use `defineLifecycle()` in `app/lifecycle.ts` to run code when the server starts, shuts down, or encounters an error. The shutdown hook runs on **any** exit signal (`SIGTERM`, `SIGINT`, `SIGUSR2`, `beforeExit`, and uncaught exceptions), so database connections are always closed cleanly.
 
 ```ts
 // app/lifecycle.ts
 import { defineLifecycle } from "@bractjs/bractjs";
 import { db } from "./db.server.ts";
+import * as Sentry from "@sentry/bun";
 
 export default defineLifecycle({
   async onStart() {
@@ -458,6 +459,12 @@ export default defineLifecycle({
     await db.disconnect();
     console.log("Database disconnected");
   },
+  async onError(err, request) {
+    // request is undefined for process-level uncaught exceptions
+    Sentry.captureException(err, {
+      extra: { url: request?.url },
+    });
+  },
 });
 ```
 
@@ -474,7 +481,22 @@ createServer({ port: 3000, ...lifecycle });
 | Hook | When it runs |
 |------|-------------|
 | `onStart` | Once, after the server begins accepting requests |
-| `onShutdown` | Before process exit — any signal or uncaught exception |
+| `onShutdown` | Before process exit — any signal, programmatic `stop()`, or uncaught exception |
+| `onError` | Every unexpected error: loader failures, action throws, uncaught exceptions. Redirects and `HttpError` throws are intentional control flow and are **not** reported. |
+
+### Programmatic stop vs signal-driven termination
+
+`createServer()` returns a `{ stop }` handle:
+
+```ts
+const srv = createServer({ port: 3000 });
+// later:
+srv.stop();          // runs onShutdown, closes the listener, does NOT exit the process
+```
+
+`stop()` returns the process to a normal idle state — useful in tests, integration harnesses, or any parent that wants to manage its own lifecycle. It does **not** call `process.exit()`.
+
+The full termination path (`process.exit(0)`) only fires when a signal handler picks up the shutdown: `SIGTERM`, `SIGINT`, `SIGUSR2`, or `uncaughtException`. If you want a programmatic stop to terminate the process, call `process.exit(0)` yourself after `stop()` returns.
 
 ---
 
@@ -494,6 +516,7 @@ All fields are optional. BractJS works with zero configuration.
 | `clientEnv` | `string[]` | `[]` | `process.env` keys exposed to the client |
 | `onStart` | `() => void \| Promise<void>` | — | Called once after the server starts listening |
 | `onShutdown` | `() => void \| Promise<void>` | — | Called before process exit on any signal |
+| `onError` | `(err, request?) => void \| Promise<void>` | — | Called on every unexpected error; `request` is `undefined` for process-level exceptions |
 
 ---
 
@@ -506,11 +529,102 @@ All fields are optional. BractJS works with zero configuration.
 | `bractjs build` | Dual server + client build with content-hashed output |
 | `bractjs start` | Serve the production build |
 | `bractjs codegen [app] [out]` | Generate typed route types into `app/route-types.gen.ts` |
+| `bractjs codegen:registry [app]` | Generate `app/_generated/{routes,actions}.ts` (single-binary prep) |
+| `bractjs codegen:manifest [app] [build]` | Snapshot `route-manifest.json` into `app/_generated/manifest.ts` |
+| `bractjs compile [outfile] [entry]` | Full single-binary pipeline (codegen → build → compile) |
 
 The CLI is a thin convenience layer. Every command delegates to a public programmatic API — you can call the same functions directly from your own scripts without the CLI.
 
 ---
 
+## Single-Binary Deployment (`bun build --compile`)
+
+BractJS can be packaged as a single executable using Bun's `--compile` flag. Because `bun build --compile` can't trace runtime filesystem scans or dynamic `import(absPath)` calls, BractJS provides a codegen step that materialises every route, layout, and server action into static imports. The compiled binary has zero filesystem dependence at startup.
+
+### One-shot
+
+```sh
+bractjs compile ./myapp
+# Equivalent to:
+#   bractjs codegen:registry      # writes app/_generated/{routes,actions}.ts
+#   bractjs build                 # writes build/client/* + route-manifest.json
+#   bractjs codegen:manifest      # snapshots manifest → app/_generated/manifest.ts
+#   bun build --compile app/server.ts --outfile ./myapp
+```
+
+### Manual pipeline (custom build step)
+
+```sh
+bractjs codegen:registry                          # A — scan routes/actions
+bractjs build                                     # B — client + server bundles
+bractjs codegen:manifest                          # C — embed manifest as a TS constant
+bun build --compile app/server.ts \               # D — single binary
+  --asset build/client/ \                         #     (embeds JS/CSS into the binary)
+  --outfile ./myapp
+```
+
+Asset embedding (`--asset build/client/`) is optional. Without it you ship `myapp` + the `build/client/` folder side-by-side. With it, you get a true single file.
+
+### The `app/server.ts` entry
+
+The scaffold template (`bractjs new`) includes `app/server.ts`:
+
+```ts
+import { createServer } from "@bractjs/bractjs";
+import { routeFiles, moduleRegistry } from "./_generated/routes.ts";
+import { actionModules } from "./_generated/actions.ts";
+import { manifest } from "./_generated/manifest.ts";
+
+createServer({
+  port: Number(process.env.PORT ?? 3000),
+  appDir: "./app",
+  publicDir: "./public",
+  manifest,
+  routeFiles,      // skips Bun.Glob route scan
+  moduleRegistry,  // skips dynamic import(absPath) of route modules
+  actionModules,   // skips Bun.Glob + dynamic import for "use server" files
+});
+```
+
+When all four of `manifest`, `routeFiles`, `moduleRegistry`, and `actionModules` are present, the server boots with **no filesystem reads of `appDir`** — the routing trie, layout chain, server-action registry, and asset manifest all come from the pre-imported modules.
+
+### Custom client builds — required plugins
+
+If you write your own `Bun.build()` call (instead of running `bractjs build`), you MUST apply these plugins or face crashes / secret leaks:
+
+| Bundle | Plugin | What breaks without it |
+|---|---|---|
+| Server | `useClientStubPlugin` | Server binary crashes when React tries to invoke browser-only hooks/APIs from `"use client"` modules |
+| Client | `createUseServerProxyPlugin(appDir)` | Server-action bodies (DB queries, secrets) ship inside the browser JS |
+| Client | `serverOnlyPlugin` | Imports of `*.server.ts` leak into the client bundle |
+| Client | `clientEnvPlugin(allowedKeys, env)` | Server env vars leak into the browser bundle |
+| Client | `cssModulesPlugin` | `*.module.css` imports don't resolve |
+
+```ts
+import {
+  useClientStubPlugin,
+  createUseServerProxyPlugin,
+  serverOnlyPlugin,
+  clientEnvPlugin,
+  cssModulesPlugin,
+} from "@bractjs/bractjs";
+
+// Server bundle (target: "bun"):
+plugins: [useClientStubPlugin];
+
+// Client bundle (target: "browser"):
+plugins: [
+  serverOnlyPlugin,
+  createUseServerProxyPlugin("./app"),
+  clientEnvPlugin(["PUBLIC_API_URL"], Bun.env as Record<string, string>),
+  cssModulesPlugin,
+];
+```
+
+The `createUseServerProxyPlugin(appDir)` factory exists because server-action IDs are SHA-256 hashes of the appDir-relative path. If the server and client compute different paths (e.g. CI vs prod), every `/_action?id=...` returns 404. Always pass the same `appDir` you pass to `createServer`.
+
+---
+
 ## Programmatic API
 
 All three runtime operations are importable, so BractJS can be embedded in existing servers or custom build scripts without the CLI.
@@ -576,8 +690,13 @@ createServer({ port: 3000, buildDir: "./build", ...lifecycle });
 my-app/
 ├── app/
 │   ├── root.tsx              # required — <html> shell
-│   ├── lifecycle.ts          # optional — onStart / onShutdown hooks
+│   ├── server.ts             # bun build --compile entrypoint (single-binary build)
+│   ├── lifecycle.ts          # optional — onStart / onShutdown / onError hooks
 │   ├── route-types.gen.ts    # generated by bractjs codegen
+│   ├── _generated/           # generated by bractjs codegen:registry / codegen:manifest
+│   │   ├── routes.ts         # static imports for routes + layouts + root
+│   │   ├── actions.ts        # static imports for "use server" modules
+│   │   └── manifest.ts       # inline ServerManifest constant
 │   ├── actions.ts            # "use server" actions
 │   └── routes/
 │       ├── _index.tsx        # → /
@@ -596,6 +715,8 @@ my-app/
     └── route-manifest.json
 ```
 
+The `_generated/` directory is only required for the single-binary workflow. Regular `bractjs dev` / `bractjs build` / `bractjs start` work without it.
+
 ---
 
 ## Architecture
@@ -623,10 +744,19 @@ Build pipeline (`bractjs build`):
 ```
 1. codegen        → app/route-types.gen.ts
 2. server bundle  → Bun.build (target: bun)   + useClientStubPlugin
-3. client bundle  → Bun.build (target: browser, splitting) + useServerProxyPlugin
+3. client bundle  → Bun.build (target: browser, splitting) + createUseServerProxyPlugin(appDir)
 4. content-hash   → rename outputs, write route-manifest.json
 ```
 
+Single-binary pipeline (`bractjs compile`):
+```
+A. registry codegen → app/_generated/{routes,actions}.ts (static imports)
+B. dual build       → build/server/, build/client/, route-manifest.json
+C. manifest codegen → app/_generated/manifest.ts (inline constant)
+D. bun build        → single executable with no runtime fs scans
+   --compile app/server.ts [--asset build/client/]
+```
+
 ---
 
 ## Package Structure
@@ -637,7 +767,7 @@ bractjs/
 │   ├── server/      # SSR, routing, loaders, actions, sessions, action-registry
 │   ├── client/      # hydrateRoot, contexts, hooks, Link/Form/Image components
 │   ├── build/       # Bun.build orchestration, manifest, hashing, directives
-│   ├── codegen/     # route-types.gen.ts generator
+│   ├── codegen/     # route-types.gen.ts + module-registry codegen (_generated/*)
 │   ├── image/       # /_image handler, ImageMagick optimizer, LRU cache
 │   ├── dev/         # watcher, HMR server + client, error overlay
 │   ├── shared/      # types, errors, deferred, context
@@ -676,8 +806,9 @@ bractjs/
 - Typed routes codegen (`AppRoutes`, `RouteParams<T>`, `TypedLoaderArgs<T>`, `routes` builder)
 - `"use server"` / `"use client"` directive system with `/_action` endpoint
 - **Programmatic API** — `createDevServer`, `runBuild`, `loadUserConfig` importable without the CLI
+- **Native `bun build --compile` support** — module-registry codegen produces single-binary deployables; build plugins exported from the public API; action IDs use relative paths for cross-machine stability
 
-Remaining on the roadmap: Edge runtime (Cloudflare Workers), CSS modules, i18n routing, streaming `useFetcher()`.
+Remaining on the roadmap: streaming `useFetcher()` (full implementation).
 
 ---
 

package/bin/cli.ts

@@ -35,6 +35,28 @@ async function scaffoldNew(appName: string): Promise<void> {
     process.exit(result.exitCode ?? 1);
   }
 
+  // Seed `app/_generated/` so the template's `app/server.ts` typechecks
+  // before the user runs a build. Only the route/action registries can run
+  // here (no manifest yet — that needs `bractjs build` first). The manifest
+  // module is stubbed in below.
+  console.log("Seeding _generated/ registries...");
+  try {
+    const { writeModuleRegistries } = await import("../src/codegen/module-registry.ts");
+    await writeModuleRegistries(join(appDir, "app"));
+    // Manifest stub — overwritten by `bractjs codegen:manifest` after a build
+    const stubManifest = [
+      "// Stub manifest — replaced by `bractjs codegen:manifest` after running",
+      "// `bractjs build`. Allows `app/server.ts` to typecheck before the",
+      "// first build completes.",
+      `import type { ServerManifest } from "@bractjs/bractjs";`,
+      `export const manifest: ServerManifest = { clientEntry: "/build/client/client.js", routes: {} };`,
+      "",
+    ].join("\n");
+    await Bun.write(join(appDir, "app", "_generated", "manifest.ts"), stubManifest);
+  } catch (err) {
+    console.warn("[bract] codegen seed skipped:", err instanceof Error ? err.message : err);
+  }
+
   console.log(`\n✓ Created ${appName}\n`);
   console.log("Next steps:");
   console.log(`  cd ${appName}`);
@@ -99,14 +121,80 @@ switch (command) {
     break;
   }
 
+  case "codegen:registry": {
+    // Phase A of the `bun build --compile` pipeline: scan routes/layouts and
+    // server actions, then write static-import registries under
+    // `<appDir>/_generated/` so the resulting bundle has no fs-scan or
+    // `import(absPath)` calls at runtime.
+    const { writeModuleRegistries } = await import("../src/codegen/module-registry.ts");
+    const appDir = resolve(process.cwd(), process.argv[3] ?? "./app");
+    const { routesPath, actionsPath } = await writeModuleRegistries(appDir);
+    console.log("[bract] registry codegen →", routesPath);
+    console.log("[bract] registry codegen →", actionsPath);
+    break;
+  }
+
+  case "codegen:manifest": {
+    // Phase C of the pipeline: snapshot `<buildDir>/route-manifest.json`
+    // into `<appDir>/_generated/manifest.ts` so the compiled binary never
+    // reads the JSON from disk at startup. Must run AFTER the client build.
+    const { writeManifestModule } = await import("../src/codegen/module-registry.ts");
+    const appDir = resolve(process.cwd(), process.argv[3] ?? "./app");
+    const buildDir = resolve(process.cwd(), process.argv[4] ?? "./build");
+    const out = await writeManifestModule(appDir, buildDir);
+    console.log("[bract] manifest codegen →", out);
+    break;
+  }
+
+  case "compile": {
+    // Convenience: run the entire `bun build --compile` pipeline.
+    // A) registry codegen → B) client build → C) manifest codegen → D) compile.
+    // The user can also invoke A/C and D separately if they want a custom
+    // client build step.
+    if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
+    const { writeModuleRegistries, writeManifestModule } = await import("../src/codegen/module-registry.ts");
+    const { runBuild } = await import("../src/build/bundler.ts");
+    const { loadUserConfig } = await import("../src/config/load.ts");
+
+    const appDir = resolve(process.cwd(), "./app");
+    const buildDir = resolve(process.cwd(), "./build");
+    const outFile = process.argv[3] ?? "./bractjs-app";
+    const entryPath = process.argv[4] ?? "./app/server.ts";
+
+    console.log("[bract] (1/4) registry codegen…");
+    await writeModuleRegistries(appDir);
+
+    console.log("[bract] (2/4) client + server build…");
+    const userCfg = await loadUserConfig();
+    await runBuild({ appDir: "./app", buildDir: "./build", ...userCfg });
+
+    console.log("[bract] (3/4) manifest codegen…");
+    await writeManifestModule(appDir, buildDir);
+
+    console.log("[bract] (4/4) bun build --compile →", outFile);
+    const result = Bun.spawnSync(
+      ["bun", "build", "--compile", entryPath, "--outfile", outFile],
+      { cwd: process.cwd(), stdio: ["inherit", "inherit", "inherit"] },
+    );
+    if (result.exitCode !== 0) {
+      console.error("[bract] bun build --compile failed");
+      process.exit(result.exitCode ?? 1);
+    }
+    console.log(`[bract] ✓ single-binary build complete: ${outFile}`);
+    break;
+  }
+
   default:
     console.log(
       "Usage: bractjs <command>\n" +
-        "  new      <app-name>    Scaffold a new BractJS app\n" +
-        "  dev                    Start dev server with HMR\n" +
-        "  build                  Build for production\n" +
-        "  start                  Start production server\n" +
-        "  codegen  [app] [out]   Generate typed route types",
+        "  new      <app-name>            Scaffold a new BractJS app\n" +
+        "  dev                            Start dev server with HMR\n" +
+        "  build                          Build for production (build/ dir)\n" +
+        "  start                          Start production server\n" +
+        "  codegen  [app] [out]           Generate typed route types\n" +
+        "  codegen:registry  [app]        Generate _generated/{routes,actions}.ts\n" +
+        "  codegen:manifest  [app] [build]  Generate _generated/manifest.ts\n" +
+        "  compile  [outfile] [entry]     Full single-binary pipeline",
     );
     process.exit(1);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Production-grade SSR framework for Bun + React 19. File-based routing, streaming SSR, server actions, typed routes.",
   "license": "MIT",
   "homepage": "https://github.com/bractjs/bractjs#readme",

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

@@ -1,12 +1,21 @@
 import { test, expect, describe, beforeAll, afterAll } from "bun:test";
 import { mkdir, rm, writeFile } from "node:fs/promises";
-import { resolve, join } from "node:path";
-import { loadServerActions, resolveAction } from "../server/action-registry.ts";
+import { resolve, relative, isAbsolute } from "node:path";
+import { loadServerActions, loadServerActionsFromRegistry, resolveAction } from "../server/action-registry.ts";
 
 const TMP = resolve(import.meta.dir, ".tmp-action-registry");
 
-async function computeId(filePath: string, name: string): Promise<string> {
-  const raw = new TextEncoder().encode(filePath + "#" + name);
+// Mirrors `pathKeyForAction` in src/server/action-registry.ts + src/build/directives.ts.
+// Action IDs are SHA-256(appDir-relative path + "#" + name) so the IDs are
+// stable across machines and inside a compiled binary.
+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): Promise<string> {
+  const raw = new TextEncoder().encode(pathKey(absPath, TMP) + "#" + name);
   const buf = await crypto.subtle.digest("SHA-256", raw);
   return Array.from(new Uint8Array(buf))
     .map((b) => b.toString(16).padStart(2, "0"))
@@ -16,30 +25,30 @@ async function computeId(filePath: string, name: string): Promise<string> {
 
 beforeAll(async () => {
   await rm(TMP, { recursive: true, force: true });
-  await mkdir(join(TMP, "routes"), { recursive: true });
-  await mkdir(join(TMP, "lib"), { recursive: true });
+  await mkdir(resolve(TMP, "routes"), { recursive: true });
+  await mkdir(resolve(TMP, "lib"), { recursive: true });
 
   // Eligible: routes/ file with real "use server" directive
   await writeFile(
-    join(TMP, "routes", "_index.tsx"),
+    resolve(TMP, "routes", "_index.tsx"),
     `"use server";\nexport async function realAction() { return 1; }\n`,
   );
 
   // Eligible by suffix: .server.ts
   await writeFile(
-    join(TMP, "lib", "thing.server.ts"),
+    resolve(TMP, "lib", "thing.server.ts"),
     `"use server";\nexport async function suffixAction() { return 2; }\n`,
   );
 
   // Ineligible: arbitrary lib file (no .server suffix, not in routes/)
   await writeFile(
-    join(TMP, "lib", "helpers.ts"),
+    resolve(TMP, "lib", "helpers.ts"),
     `"use server";\nexport async function shouldNotLoad() { return 3; }\n`,
   );
 
   // Ineligible: "use server" inside a template literal (not at start-of-file)
   await writeFile(
-    join(TMP, "routes", "fake.tsx"),
+    resolve(TMP, "routes", "fake.tsx"),
     `const s = \`use server\`;\nexport async function notADirective() { return 4; }\n`,
   );
 
@@ -52,22 +61,53 @@ afterAll(async () => {
 
 describe("loadServerActions — eligibility", () => {
   test("routes/ file with real directive registers exports", async () => {
-    const id = await computeId(join(TMP, "routes", "_index.tsx"), "realAction");
+    const id = await computeId(resolve(TMP, "routes", "_index.tsx"), "realAction");
     expect(resolveAction(id)).not.toBeNull();
   });
 
   test(".server.ts file registers exports", async () => {
-    const id = await computeId(join(TMP, "lib", "thing.server.ts"), "suffixAction");
+    const id = await computeId(resolve(TMP, "lib", "thing.server.ts"), "suffixAction");
     expect(resolveAction(id)).not.toBeNull();
   });
 
   test("ineligible path (lib/*.ts) does NOT register", async () => {
-    const id = await computeId(join(TMP, "lib", "helpers.ts"), "shouldNotLoad");
+    const id = await computeId(resolve(TMP, "lib", "helpers.ts"), "shouldNotLoad");
     expect(resolveAction(id)).toBeNull();
   });
 
   test("'use server' inside template literal does NOT register", async () => {
-    const id = await computeId(join(TMP, "routes", "fake.tsx"), "notADirective");
+    const id = await computeId(resolve(TMP, "routes", "fake.tsx"), "notADirective");
     expect(resolveAction(id)).toBeNull();
   });
 });
+
+describe("loadServerActionsFromRegistry", () => {
+  test("statically-imported modules register under SHA-256(relPath#name)", async () => {
+    // Action ID must match what the client proxy plugin would emit. The
+    // codegen path passes relPath directly (no appDir stripping needed) so
+    // the hash input is the literal entry.relPath string.
+    async function rawId(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 fakeMod = {
+      sendEmail: async (to: string) => `sent ${to}`,
+      __ignored: 42, // non-function — must be skipped
+    };
+    await loadServerActionsFromRegistry([
+      { relPath: "routes/contact.server.ts", mod: fakeMod },
+    ]);
+    const id = await rawId("routes/contact.server.ts", "sendEmail");
+    const fn = resolveAction(id);
+    expect(fn).not.toBeNull();
+    expect(await fn!("a@b.com")).toBe("sent a@b.com");
+
+    const ignored = await rawId("routes/contact.server.ts", "__ignored");
+    expect(resolveAction(ignored)).toBeNull();
+  });
+});

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

@@ -0,0 +1,95 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import {
+  resolveRouteChain,
+  resolveLayoutChainFromRegistry,
+  type ModuleRegistry,
+} from "../server/layout.ts";
+
+const TMP = resolve(import.meta.dir, ".tmp-layout-registry");
+
+// Sentinel default components let us distinguish which module ended up where.
+const rootModule = { default: () => "root" } as const;
+const blogLayoutModule = { default: () => "blog-layout" } as const;
+const blogPostModule = { default: () => "blog-post" } as const;
+const indexModule = { default: () => "index" } as const;
+
+const registry: ModuleRegistry = {
+  "root.tsx": rootModule,
+  "routes/blog/layout.tsx": blogLayoutModule,
+  "routes/blog/[slug].tsx": blogPostModule,
+  "routes/_index.tsx": indexModule,
+};
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(join(TMP, "routes", "blog"), { recursive: true });
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("resolveLayoutChainFromRegistry", () => {
+  test("includes root + ancestor layouts in order", () => {
+    const r = resolveLayoutChainFromRegistry(
+      { filePath: "routes/blog/[slug].tsx", urlPattern: "blog/[slug]", segments: ["blog", { param: "slug" }] },
+      registry,
+    );
+    expect(r.layoutFiles).toEqual(["root.tsx", "routes/blog/layout.tsx"]);
+  });
+
+  test("omits root when registry has no root entry", () => {
+    const r = resolveLayoutChainFromRegistry(
+      { filePath: "routes/_index.tsx", urlPattern: "", segments: [] },
+      { "routes/_index.tsx": indexModule },
+    );
+    expect(r.layoutFiles).toEqual([]);
+  });
+
+  test("matches sibling-dir layouts only when route is deeper", () => {
+    // urlPattern "blog" → layoutDirs returns [] (no ancestor)
+    const r = resolveLayoutChainFromRegistry(
+      { filePath: "routes/blog/_index.tsx", urlPattern: "blog", segments: ["blog"] },
+      registry,
+    );
+    expect(r.layoutFiles).toEqual(["root.tsx"]);
+  });
+});
+
+describe("resolveRouteChain — registry mode", () => {
+  test("returns the pre-loaded route module without touching disk", async () => {
+    const chain = await resolveRouteChain(
+      { filePath: "routes/blog/[slug].tsx", urlPattern: "blog/[slug]", segments: ["blog", { param: "slug" }] },
+      // appDir intentionally points at a path that does NOT exist — registry mode
+      // must skip every fs check.
+      "/nonexistent/appdir",
+      registry,
+    );
+    expect(chain.root.default).toBe(rootModule.default);
+    expect(chain.layouts).toHaveLength(1);
+    expect(chain.layouts[0].default).toBe(blogLayoutModule.default);
+    expect(chain.route.default).toBe(blogPostModule.default);
+  });
+
+  test("missing route key yields an empty module shape (no throw)", async () => {
+    const chain = await resolveRouteChain(
+      { filePath: "routes/missing.tsx", urlPattern: "missing", segments: ["missing"] },
+      "/nonexistent",
+      registry,
+    );
+    expect(chain.route.default).toBeUndefined();
+    expect(chain.route.loader).toBeUndefined();
+    expect(chain.root.default).toBe(rootModule.default);
+  });
+
+  test("forward-slash normalisation: filePath with backslashes resolves the same key", async () => {
+    const chain = await resolveRouteChain(
+      { filePath: "routes\\blog\\[slug].tsx", urlPattern: "blog/[slug]", segments: ["blog", { param: "slug" }] },
+      "/nonexistent",
+      registry,
+    );
+    expect(chain.route.default).toBe(blogPostModule.default);
+  });
+});