@bractjs/bractjs 0.1.27 → 0.1.28

package/src/__tests__/security.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { test, expect, describe, beforeAll, afterAll, spyOn } from "bun:test";
 import { mkdir, rm, writeFile, symlink } from "node:fs/promises";
 import { resolve, join, relative, isAbsolute } from "node:path";
 import { tmpdir } from "node:os";
@@ -104,6 +104,48 @@ describe("action-handler — arg validation", () => {
     expect(res?.status).toBe(400);
   });
 
+  test("nested __proto__ below the old depth-20 cap → 400 (scan reaches it)", async () => {
+    // Build a raw JSON string so "__proto__" is an OWN key (an object literal
+    // would set the prototype instead). Bury it 24 levels deep — past the old
+    // depth-20 short-circuit that previously let it slip through.
+    let body = '{"__proto__":{"polluted":true}}';
+    for (let i = 0; i < 24; i++) body = `{"a":${body}}`;
+    const req = new Request(`http://x/_action?id=${registeredActionId}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: `[${body}]`,
+    });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(400);
+  });
+
+  test("payload nested past MAX_SCAN_DEPTH → 400 (fails closed)", async () => {
+    // Over-deep nesting with NO forbidden key must still be rejected: a
+    // security scan that can't see the bottom must not pass it through.
+    let body = '{"value":"x"}';
+    for (let i = 0; i < 250; i++) body = `{"a":${body}}`;
+    const req = new Request(`http://x/_action?id=${registeredActionId}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: `[${body}]`,
+    });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(400);
+  });
+
+  test("normal nested payload (within cap) still succeeds", async () => {
+    // A legitimately nested object (no forbidden keys) must NOT be rejected.
+    let obj: Record<string, unknown> = { value: "ok" };
+    for (let i = 0; i < 30; i++) obj = { nested: obj };
+    const req = new Request(`http://x/_action?id=${registeredActionId}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: JSON.stringify([obj]),
+    });
+    const res = await handleActionRequest(req);
+    expect(res?.status).toBe(200);
+  });
+
   test("JSON body > 1 MiB rejected with 413 (advertised via Content-Length)", async () => {
     const huge = "a".repeat(2 * 1024 * 1024);
     const req = new Request(`http://x/_action?id=${registeredActionId}`, {
@@ -135,6 +177,45 @@ describe("action-handler — arg validation", () => {
   });
 });
 
+// ── F2 — reserved route exports are not registered as actions ──────────────
+
+describe("action-registry — reserved route exports", () => {
+  const TMP = resolve(import.meta.dir, ".tmp-reserved-exports");
+
+  beforeAll(async () => {
+    await rm(TMP, { recursive: true, force: true });
+    await mkdir(join(TMP, "routes"), { recursive: true });
+    await writeFile(
+      join(TMP, "routes", "page.tsx"),
+      `"use server";
+export async function loader() { return { secret: "leaked" }; }
+export async function action() { return "mutated"; }
+export default function Page() { return null; }
+export async function doThing() { return "ok"; }
+`,
+    );
+    await loadServerActions(TMP);
+  });
+
+  afterAll(async () => {
+    await rm(TMP, { recursive: true, force: true });
+  });
+
+  test("loader / action / default in a routes/ file are NOT resolvable as actions", async () => {
+    const { resolveAction } = await import("../server/action-registry.ts");
+    for (const name of ["loader", "action", "default"]) {
+      const id = await computeId(join(TMP, "routes", "page.tsx"), name, TMP);
+      expect(resolveAction(id)).toBeNull();
+    }
+  });
+
+  test("a genuine named export in the same file IS resolvable", async () => {
+    const { resolveAction } = await import("../server/action-registry.ts");
+    const id = await computeId(join(TMP, "routes", "page.tsx"), "doThing", TMP);
+    expect(resolveAction(id)).not.toBeNull();
+  });
+});
+
 // ── Item 3 — CSRF ─────────────────────────────────────────────────────────
 
 describe("CSRF — cross-origin mutation", () => {
@@ -166,6 +247,34 @@ describe("CSRF — cross-origin mutation", () => {
     });
     expect(res.status).toBe(403);
   });
+
+  test("403 body is terse in prod (no info disclosure)", async () => {
+    // This server runs in prod mode (NODE_ENV unset) — the body must not
+    // include the dev hint.
+    const res = await fetch(`${BASE}/`, {
+      method: "POST",
+      body: new FormData(),
+      headers: { Origin: "https://evil.example" },
+    });
+    expect(await res.text()).toBe("Forbidden");
+  });
+
+  test("csrfForbiddenResponse explains the fix in dev, stays terse in prod", async () => {
+    const { csrfForbiddenResponse } = await import("../server/csrf.ts");
+    const original = Bun.env.NODE_ENV;
+    const spy = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      Bun.env.NODE_ENV = "development";
+      expect(await csrfForbiddenResponse().text()).toContain("X-BractJS-Action");
+
+      Bun.env.NODE_ENV = "production";
+      expect(await csrfForbiddenResponse().text()).toBe("Forbidden");
+    } finally {
+      if (original === undefined) delete Bun.env.NODE_ENV;
+      else Bun.env.NODE_ENV = original;
+      spy.mockRestore();
+    }
+  });
 });
 
 describe("CSRF — Sec-Fetch-Site (isAllowedMutation)", () => {

package/src/__tests__/selective-ssr.test.ts

@@ -0,0 +1,85 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { createServer } from "../server/serve.ts";
+
+const PORT = 3994;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+});
+
+/** The rendered document without the __BRACTJS_DATA__ script island. */
+function withoutScripts(html: string): string {
+  return html.replace(/<script[\s\S]*?<\/script>/g, "");
+}
+
+describe("ssr: false (client-only)", () => {
+  test("document SSR renders the Fallback, never the component or loader data", async () => {
+    const res = await fetch(`${BASE}/client-only`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    const rendered = withoutScripts(html);
+    expect(rendered).toContain("client-only fallback");
+    expect(rendered).not.toContain("client-only component");
+    // The loader must not have run at all — its data appears nowhere, not
+    // even in the bootstrap payload.
+    expect(html).not.toContain("CLIENT-ONLY-LOADER-DATA");
+    expect(html).toContain('"ssrMode":"client-only"');
+  });
+
+  test("/_data DOES run the loader — that is how the client completes the render", async () => {
+    const res = await fetch(`${BASE}/_data?path=/client-only`);
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as { route: { secret: string } };
+    expect(data.route.secret).toBe("CLIENT-ONLY-LOADER-DATA");
+  });
+
+  test("beforeLoad still gates the document — ssr:false is not an auth bypass", async () => {
+    const res = await fetch(`${BASE}/protected-client-only`);
+    expect(res.status).toBe(403);
+    const body = await res.text();
+    expect(body).not.toContain("GATED-CLIENT-ONLY-DATA");
+  });
+
+  test("beforeLoad still gates /_data for ssr:false routes", async () => {
+    const res = await fetch(`${BASE}/_data?path=/protected-client-only`);
+    expect(res.status).toBe(403);
+    const body = await res.text();
+    expect(body).not.toContain("GATED-CLIENT-ONLY-DATA");
+  });
+});
+
+describe('ssr: "data-only"', () => {
+  test("loaders run (data in bootstrap) but the Fallback renders in the component's place", async () => {
+    const res = await fetch(`${BASE}/data-only`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    const rendered = withoutScripts(html);
+    expect(rendered).toContain("data-only fallback");
+    expect(rendered).not.toContain("data-only component");
+    // Loader data IS present — in the bootstrap payload only.
+    expect(html).toContain("DATA-ONLY-LOADER-DATA");
+    expect(html).toContain('"ssrMode":"data-only"');
+  });
+});
+
+describe("default routes are untouched", () => {
+  test("a normal route still fully SSRs with no ssrMode marker", async () => {
+    const res = await fetch(`${BASE}/`);
+    const html = await res.text();
+    expect(withoutScripts(html)).toContain("Index page content");
+    expect(html).not.toContain('"ssrMode"');
+  });
+});

package/src/__tests__/spa-mode.test.ts

@@ -0,0 +1,77 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { createServer } from "../server/serve.ts";
+
+const PORT = 3993;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    ssr: false,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+});
+
+describe("SPA mode (config ssr: false)", () => {
+  test("document GETs return the static shell — no loader data, ssrMode spa", async () => {
+    const res = await fetch(`${BASE}/`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+    const html = await res.text();
+    expect(html).toContain('"ssrMode":"spa"');
+    // The index loader must not have run for the document.
+    expect(html).not.toContain("hello from bractjs");
+  });
+
+  test("every matching document path serves the same shell", async () => {
+    const a = await (await fetch(`${BASE}/`)).text();
+    const b = await (await fetch(`${BASE}/counter`)).text();
+    expect(b).toContain('"ssrMode":"spa"');
+    expect(b).toBe(a);
+  });
+
+  test("unmatched paths still 404", async () => {
+    const res = await fetch(`${BASE}/nonexistent`);
+    expect(res.status).toBe(404);
+  });
+
+  test("/_data still runs loaders — SPA mode is 'no document SSR', not 'no server'", async () => {
+    const res = await fetch(`${BASE}/_data?path=/`);
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as { route: { message: string } };
+    expect(data.route.message).toBe("hello from bractjs");
+  });
+
+  test("actions still work, with the CSRF gate intact", async () => {
+    // Same-origin mutation with the header → allowed.
+    const ok = await fetch(`${BASE}/counter`, {
+      method: "POST",
+      body: new FormData(),
+      headers: { Origin: BASE, "X-BractJS-Action": "1" },
+    });
+    expect(ok.status).toBe(200);
+    expect(((await ok.json()) as { ok: boolean }).ok).toBe(true);
+
+    // Cross-origin mutation → blocked exactly as in SSR mode.
+    const blocked = await fetch(`${BASE}/counter`, {
+      method: "POST",
+      body: new FormData(),
+      headers: { Origin: "https://evil.example" },
+    });
+    expect(blocked.status).toBe(403);
+  });
+
+  test("beforeLoad-gated /_data stays gated in SPA mode", async () => {
+    const res = await fetch(`${BASE}/_data?path=/protected`);
+    expect(res.status).toBe(403);
+  });
+});

package/src/__tests__/typed-routing.test.ts

@@ -112,6 +112,27 @@ describe("typed routing (type-level)", () => {
     await mkdir(join(app, "routes", "blog"), { recursive: true });
     await writeFile(join(app, "routes", "_index.tsx"), "export default () => null;\n");
     await writeFile(join(app, "routes", "blog", "[id].tsx"), "export default () => null;\n");
+    // A route with a typed searchSchema: its safeParse return type is what
+    // `InferSchemaOutput` (and therefore useSearch<"/posts">) must pick up.
+    // It also has a loader whose return type drives `useLoaderData<typeof loader>`:
+    // an object union with a Response branch (must be excluded) and a Deferred
+    // field (must be preserved so <Await> accepts it).
+    await writeFile(
+      join(app, "routes", "posts.tsx"),
+      `import { defer } from "@bractjs/bractjs";\n` +
+        `import type { LoaderArgs } from "@bractjs/bractjs";\n` +
+        `export const searchSchema = {\n` +
+        `  safeParse(_input: unknown): { success: boolean; data?: { page: number; q?: string } } {\n` +
+        `    return { success: true, data: { page: 1 } };\n` +
+        `  },\n` +
+        `};\n` +
+        `export function loader({ search }: LoaderArgs<{ page: number }>) {\n` +
+        `  const p: number = search.page;\n` +
+        `  if (p < 0) return new Response("bad", { status: 400 });\n` +
+        `  return { count: p, comments: defer({ list: Promise.resolve([1, 2]) }).list };\n` +
+        `}\n` +
+        `export default () => null;\n`,
+    );
 
     // Generate the registration file (augments Register on the package).
     await writeFile(join(app, "route-types.gen.ts"), await generateRouteTypes(app));
@@ -119,29 +140,58 @@ describe("typed routing (type-level)", () => {
 
     await writeFile(
       join(app, "usage.tsx"),
-      `import { Link, useNavigate, useParams, useSearchParams } from "@bractjs/bractjs";\n` +
+      `import { Link, useNavigate, useParams, useSearchParams, useSearch, useSetSearch, useLoaderData, Await } from "@bractjs/bractjs";\n` +
+        `import type { LoaderArgsFor } from "./route-types.gen.ts";\n` +
+        `import { loader } from "./routes/posts.tsx";\n` +
         `import "./route-types.gen.ts";\n` +
         `export function Ok() {\n` +
         `  const navigate = useNavigate();\n` +
         `  const p = useParams<"/blog/:id">();\n` +
         `  const id: string = p.id;\n` +
         `  useSearchParams<"/blog/:id">();\n` +
+        `  const s = useSearch<"/posts">();\n` +
+        `  const page: number = s.page;\n` +
+        `  const setSearch = useSetSearch<"/posts">();\n` +
+        `  void setSearch({ page: page + 1 });\n` +
+        `  void setSearch((prev) => ({ page: prev.page + 1 }), { replace: true });\n` +
+        `  // useLoaderData<typeof loader>(): Response branch excluded, count typed,\n` +
+        `  // Deferred field preserved + accepted by <Await>.\n` +
+        `  const data = useLoaderData<typeof loader>();\n` +
+        `  const count: number = data.count;\n` +
+        `  // LoaderArgsFor<"/posts">: full route-literal arg typing.\n` +
+        `  const argSearch = (null as unknown as LoaderArgsFor<"/posts">).search;\n` +
+        `  const argPage: number = argSearch.page;\n` +
+        `  void count; void argPage;\n` +
         `  return (<>\n` +
+        `    <Await resolve={data.comments} fallback={null}>{(list) => <span>{list.length}</span>}</Await>\n` +
         `    <Link to="/blog/:id" params={{ id }}>typed</Link>\n` +
         `    <Link to="/">static literal</Link>\n` +
+        `    <Link to="/posts" search={{ page: 2 }}>typed search</Link>\n` +
         `    <Link to={\`/\${id}\`}>built string (BC)</Link>\n` +
         `    <button onClick={() => { void navigate("/blog/:id", { params: { id } }); }}>go</button>\n` +
+        `    <button onClick={() => { void navigate("/posts", { search: { page: 3 } }); }}>paged</button>\n` +
         `    <button onClick={() => { void navigate("/"); }}>home</button>\n` +
         `  </>);\n` +
         `}\n` +
         `export function Bad() {\n` +
         `  const navigate = useNavigate();\n` +
         `  const p = useParams<"/blog/:id">();\n` +
+        `  const s = useSearch<"/posts">();\n` +
+        `  const setSearch = useSetSearch<"/posts">();\n` +
+        `  // @ts-expect-error page is a number, not a string\n` +
+        `  void setSearch({ page: "2" });\n` +
+        `  // @ts-expect-error the schema declares no \`bogus\` key\n` +
+        `  void (s.bogus);\n` +
+        `  const data = useLoaderData<typeof loader>();\n` +
+        `  // @ts-expect-error loader data has no \`missing\` field (Response branch excluded, object inferred)\n` +
+        `  void (data.missing);\n` +
         `  return (<>\n` +
         `    {/* @ts-expect-error wrong param key */}\n` +
         `    <Link to="/blog/:id" params={{ wrong: "1" }}>x</Link>\n` +
         `    {/* @ts-expect-error missing required param */}\n` +
         `    <Link to="/blog/:id" params={{}}>x</Link>\n` +
+        `    {/* @ts-expect-error search value has the wrong type */}\n` +
+        `    <Link to="/posts" search={{ page: "2" }}>x</Link>\n` +
         `    <button onClick={() => {\n` +
         `      // @ts-expect-error wrong param key in navigate\n` +
         `      void navigate("/blog/:id", { params: { wrong: "1" } });\n` +

package/src/build/bundler.ts

@@ -19,6 +19,8 @@ export interface BuildConfig {
   minify?: boolean;
   clientEnv?: string[];
   plugins?: BunPlugin[];
+  /** SPA mode: when `false`, the build also emits the static document shell. */
+  ssr?: boolean;
 }
 
 export async function runBuild(config: BuildConfig): Promise<void> {
@@ -30,6 +32,16 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   const routeFilePaths = routes.map((r) => join(appDir, r.filePath));
   const rootFilePath = join(appDir, "root.tsx");
 
+  // Static route-module lint: surface empty routes and miscased exports at
+  // build time (no execution — just source analysis).
+  const { lintRouteModuleSource } = await import("./route-lint.ts");
+  for (const r of routes) {
+    const src = await Bun.file(join(appDir, r.filePath)).text().catch(() => "");
+    for (const warning of lintRouteModuleSource(src, r.filePath)) {
+      console.warn(`[bract] ${warning}`);
+    }
+  }
+
   // ── 1. Clean stale artefacts ────────────────────────────────────────────
   const buildDir = config.buildDir ?? "build";
   await Promise.all([
@@ -140,5 +152,26 @@ export async function runBuild(config: BuildConfig): Promise<void> {
   // ── 5. Write manifest ──────────────────────────────────────────────────
   const manifest = generateManifest({ clientEntry, rootChunk, routeChunks, mode: "production" });
   await writeManifest(manifest, "build");
+
+  // ── 6. SPA shell (ssr: false) ───────────────────────────────────────────
+  // Emit the static document shell every document GET will serve in SPA mode.
+  if (config.ssr === false) {
+    const { renderSpaShell } = await import("../server/spa.ts");
+    const { installUseClientServerStub } = await import("../server/use-client-runtime.ts");
+    // root.tsx is imported from source here — "use client" components inside
+    // it must null-render exactly as they do on the running server.
+    installUseClientServerStub(appDir);
+    const serverManifest = {
+      clientEntry,
+      rootChunk,
+      routes: Object.fromEntries(
+        Object.entries(manifest.routes).map(([pat, e]) => [pat, { file: e.chunk, chunk: e.chunk }]),
+      ),
+    };
+    const html = await renderSpaShell(appDir, serverManifest);
+    await Bun.write(join(buildDir, "client", "__spa.html"), html);
+    console.log("[bract] SPA shell → build/client/__spa.html");
+  }
+
   console.log("[bract] build complete →", Object.keys(manifest.routes).length, "routes");
 }

package/src/build/prerender.ts

@@ -0,0 +1,88 @@
+import { join } from "node:path";
+import { buildFetchHandler } from "../server/serve.ts";
+import type { ServerManifest } from "../server/render.ts";
+
+export interface PrerenderOptions {
+  /** Concrete paths to prerender (or a function resolving them, e.g. from a DB). */
+  prerender: string[] | (() => string[] | Promise<string[]>);
+  appDir?: string;
+  publicDir?: string;
+  buildDir?: string;
+  /** Override the manifest instead of loading `<buildDir>/route-manifest.json`. */
+  manifest?: ServerManifest;
+}
+
+export interface PrerenderResult {
+  written: string[];
+}
+
+/**
+ * Where a path's prerendered files live under `<buildDir>/client/_prerender`.
+ * Throws on anything that isn't a clean absolute path — these strings come
+ * from user config but become filesystem writes.
+ */
+export function prerenderPaths(path: string): { html: string; data: string } {
+  if (!path.startsWith("/")) {
+    throw new Error(`[bractjs] prerender: paths must start with "/", got ${JSON.stringify(path)}`);
+  }
+  if (path.includes(":") || path.includes("[") || path.includes("*")) {
+    throw new Error(
+      `[bractjs] prerender: ${JSON.stringify(path)} looks like a route PATTERN — ` +
+        `expand dynamic routes to concrete paths (e.g. "/blog/intro", not "/blog/:slug").`,
+    );
+  }
+  const segments = path.split("/").filter(Boolean);
+  if (segments.some((s) => s === ".." || s === ".")) {
+    throw new Error(`[bractjs] prerender: refusing path with dot segments: ${JSON.stringify(path)}`);
+  }
+  const dir = segments.join("/");
+  return {
+    html: dir === "" ? "index.html" : `${dir}/index.html`,
+    data: dir === "" ? "_data.json" : `${dir}/_data.json`,
+  };
+}
+
+/**
+ * Build-time prerendering (SSG): run the production fetch handler in-process
+ * against each configured path and write the HTML document plus its `/_data`
+ * payload (used by client navigations INTO a prerendered page) under
+ * `<buildDir>/client/_prerender/`. The production server serves these before
+ * falling back to dynamic SSR — query-carrying requests stay dynamic.
+ *
+ * Loaders run for real at build time: anything they need (DB, env) must be
+ * available to the build.
+ */
+export async function runPrerender(options: PrerenderOptions): Promise<PrerenderResult> {
+  const buildDir = options.buildDir ?? "./build";
+  const paths = typeof options.prerender === "function" ? await options.prerender() : options.prerender;
+
+  const handler = buildFetchHandler({
+    appDir: options.appDir ?? "./app",
+    publicDir: options.publicDir,
+    buildDir,
+    manifest: options.manifest,
+  });
+
+  const written: string[] = [];
+  for (const path of paths) {
+    const out = prerenderPaths(path);
+
+    const htmlRes = await handler(new Request("http://prerender.local" + path));
+    if (htmlRes.status !== 200) {
+      throw new Error(`[bractjs] prerender: GET ${path} returned ${htmlRes.status}`);
+    }
+    const htmlFile = join(buildDir, "client", "_prerender", out.html);
+    await Bun.write(htmlFile, await htmlRes.text());
+    written.push(htmlFile);
+
+    const dataRes = await handler(
+      new Request("http://prerender.local/_data?path=" + encodeURIComponent(path)),
+    );
+    if (dataRes.status === 200) {
+      const dataFile = join(buildDir, "client", "_prerender", out.data);
+      await Bun.write(dataFile, await dataRes.text());
+      written.push(dataFile);
+    }
+  }
+  return { written };
+}

package/src/build/route-lint.ts

@@ -0,0 +1,49 @@
+import { extractExports } from "./directives.ts";
+
+// The canonical route-module export names. A route file exporting a near-miss
+// (wrong case) of one of these is almost always a mistake — the framework's
+// projection is case-sensitive, so `Loader` is silently ignored.
+export const ROUTE_EXPORT_NAMES = [
+  "default", "loader", "action", "meta", "beforeLoad", "shouldRevalidate",
+  "searchSchema", "ssr", "Fallback", "handle", "ErrorBoundary", "config",
+  "loaderDeps", "context",
+] as const;
+
+const CANONICAL_LOWER = new Map(ROUTE_EXPORT_NAMES.map((n) => [n.toLowerCase(), n]));
+const CANONICAL_SET = new Set<string>(ROUTE_EXPORT_NAMES);
+
+/** A route is "renderable or does work" if it has any of these. */
+const MEANINGFUL = ["default", "loader", "action", "beforeLoad"];
+
+/**
+ * Static lint of a route module's SOURCE (no execution). Returns human-readable
+ * warning strings. Used by the dev rebuilder and the production build to catch
+ * two common, silent mistakes: a route that renders nothing, and an export
+ * whose casing doesn't match a framework export (so it's ignored).
+ */
+export function lintRouteModuleSource(src: string, filePath: string): string[] {
+  const warnings: string[] = [];
+  const names = extractExports(src);
+  // extractExports misses anonymous `export default () => …` / `export default function() {}`.
+  const hasAnonDefault = /^export\s+default\b/m.test(src) && !names.includes("default");
+  const exportSet = new Set(names);
+  if (hasAnonDefault) exportSet.add("default");
+
+  if (!MEANINGFUL.some((n) => exportSet.has(n))) {
+    warnings.push(
+      `${filePath}: route has no default/loader/action/beforeLoad export — it renders an empty page.`,
+    );
+  }
+
+  for (const name of exportSet) {
+    if (CANONICAL_SET.has(name)) continue;
+    const canonical = CANONICAL_LOWER.get(name.toLowerCase());
+    if (canonical && canonical !== name) {
+      warnings.push(
+        `${filePath}: export "${name}" looks like "${canonical}" — route exports are case-sensitive, so "${name}" is ignored.`,
+      );
+    }
+  }
+
+  return warnings;
+}