@bractjs/bractjs 0.1.25 → 0.1.27

package/bin/cli.ts

@@ -173,8 +173,29 @@ switch (command) {
 
     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"] },
+      [
+        "bun",
+        "build",
+        "--compile",
+        // Bun executables disable tsconfig autoload by default. Re-enable it so
+        // React TSX keeps using the app's jsx settings at runtime.
+        "--compile-autoload-tsconfig",
+        entryPath,
+        "--outfile",
+        outFile,
+      ],
+      {
+        cwd: process.cwd(),
+        stdio: ["inherit", "inherit", "inherit"],
+        env: {
+          ...process.env,
+          // Bun executable compile currently miscompiles React TSX under
+          // NODE_ENV=production (emits jsxDEV calls against a runtime that
+          // doesn't provide jsxDEV). Force a safe compile-time env while still
+          // keeping Bract's client/server build phase in production mode.
+          NODE_ENV: "development",
+        },
+      },
     );
     if (result.exitCode !== 0) {
       console.error("[bract] bun build --compile failed");
@@ -198,4 +219,3 @@ switch (command) {
     );
     process.exit(1);
 }
-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "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__/build-path.test.ts

@@ -0,0 +1,29 @@
+import { test, expect, describe } from "bun:test";
+import { buildPath } from "../client/build-path.ts";
+
+describe("buildPath", () => {
+  test("substitutes a single :param", () => {
+    expect(buildPath("/blog/:id", { id: "42" })).toBe("/blog/42");
+  });
+
+  test("substitutes multiple params", () => {
+    expect(buildPath("/u/:user/post/:post", { user: "ann", post: "7" })).toBe("/u/ann/post/7");
+  });
+
+  test("passes static patterns through untouched", () => {
+    expect(buildPath("/about", {})).toBe("/about");
+    expect(buildPath("/", {})).toBe("/");
+  });
+
+  test("URL-encodes param values", () => {
+    expect(buildPath("/search/:q", { q: "a b/c" })).toBe("/search/a%20b%2Fc");
+  });
+
+  test("coerces numbers to strings", () => {
+    expect(buildPath("/n/:id", { id: 7 })).toBe("/n/7");
+  });
+
+  test("leaves an absent param's segment intact (surfaces as an obvious bad URL)", () => {
+    expect(buildPath("/blog/:id", {})).toBe("/blog/:id");
+  });
+});

package/src/__tests__/codegen.test.ts

@@ -29,6 +29,42 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/\| "\/users\/:id"/);
   });
 
+  test("wires the Register augmentation for typed routing", async () => {
+    const regApp = join(tmpdir(), `bract-codegen-register-${Date.now()}`);
+    await mkdir(join(regApp, "routes", "users"), { recursive: true });
+    await writeFile(join(regApp, "routes", "about.tsx"), "export default () => null;");
+    await writeFile(join(regApp, "routes", "users", "[id].tsx"), "export default () => null;");
+
+    const out = await generateRouteTypes(regApp);
+
+    // Bug 1 regression: the augmentation must target the real package name.
+    expect(out).toContain('declare module "@bractjs/bractjs"');
+    expect(out).not.toMatch(/declare module ['"]bractjs['"]/);
+
+    // Bug 2 regression: the customization maps are AUGMENTED on the package, not
+    // re-declared as bare top-level interfaces in the app file.
+    expect(out).not.toMatch(/^export interface RouteSearchParamsMap/m);
+    expect(out).not.toMatch(/^export interface RouteContextMap/m);
+    expect(out).toContain('import type { RouteSearchParamsMap, RouteContextMap } from "@bractjs/bractjs"');
+
+    // The Register seam carries the route union and a per-route params map.
+    expect(out).toContain("interface Register {");
+    expect(out).toContain("routes: AppRoutes;");
+    expect(out).toMatch(/"\/users\/:id": \{ id: string \};/); // dynamic route → typed params
+    expect(out).toMatch(/"\/about": \{\};/);                   // static route → no params
+
+    await rm(regApp, { recursive: true, force: true });
+  });
+
+  test("emits no Register augmentation when there are no routes", async () => {
+    const emptyApp = join(tmpdir(), `bract-codegen-empty-${Date.now()}`);
+    await mkdir(join(emptyApp, "routes"), { recursive: true });
+    const out = await generateRouteTypes(emptyApp);
+    expect(out).toContain("export type AppRoutes =\n  never;");
+    expect(out).not.toContain("interface Register {");
+    await rm(emptyApp, { recursive: true, force: true });
+  });
+
   test("rejects hostile filenames at codegen time", async () => {
     const hostileApp = join(tmpdir(), `bract-codegen-hostile-${Date.now()}`);
     await mkdir(join(hostileApp, "routes"), { recursive: true });

package/src/__tests__/compile-safety.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Static guardrail for the `bun build --compile` single-executable feature.
+ *
+ * `bun build --compile` CANNOT trace two things at runtime:
+ *   1. `Bun.Glob(...).scan()` filesystem scans
+ *   2. dynamic `import(<variable>)` calls
+ *
+ * The framework supports single-binary deployment by materialising routes,
+ * layouts, actions, and the manifest into STATIC imports (`app/_generated/*`)
+ * and having `createServer()` accept them via `routeFiles` / `moduleRegistry`
+ * / `actionModules` / `manifest`. The registry-mode code path therefore must
+ * contain NO glob scans and NO variable `import()` — otherwise the compiled
+ * binary silently breaks at request time.
+ *
+ * This test scans the server source (the only graph compiled into the binary)
+ * and fails if a NEW unguarded `Bun.Glob` / variable-`import()` appears outside
+ * the known dev-fallback functions. It runs in milliseconds — a fast tripwire
+ * that complements the heavyweight compile-smoke e2e test.
+ *
+ * NOTE: `src/client/**` is intentionally NOT scanned — the client bundle is
+ * built for the browser (target=browser) and lazy-loads route chunks via
+ * dynamic `import(chunkUrl)`, which is correct there. Only the SERVER binary is
+ * subject to `bun build --compile` tracing. `src/dev/**` is also excluded: it
+ * never ships in a production/compiled server (all dev endpoints are gated by
+ * `isExplicitDev()` and dev modules are loaded via string-literal imports).
+ */
+import { test, expect, describe } from "bun:test";
+import { resolve } from "node:path";
+
+const SERVER_DIR = resolve(import.meta.dir, "../server");
+
+// Occurrences of fs-scan / variable-import that are KNOWN-SAFE because they
+// live in the dev-fallback path, which is skipped whenever the registry config
+// (routeFiles / actionModules / moduleRegistry) is provided — i.e. always in a
+// compiled binary. Keyed by file (relative to src/server) → the substrings of
+// the enclosing dev-fallback function/usage we accept.
+//
+// If you add a new fs-scan or variable-import on the server path, this test
+// will fail. Either gate it behind the registry config (and the isExplicitDev
+// pattern), or — if it is genuinely a new dev-only fallback — extend this map
+// with a justification.
+const ALLOWED: Record<string, string[]> = {
+  // scanRoutes(): the startup route scan, bypassed when `routeFiles` is set
+  // (see buildFetchHandler in serve.ts).
+  "scanner.ts": ["routes/**/*.{tsx,ts}"],
+  // loadServerActions(): the startup action scan + dynamic import, bypassed
+  // when `actionModules` is set. loadServerActionsFromRegistry() is the
+  // compiled-binary counterpart and uses neither.
+  "action-registry.ts": ["**/*.{ts,tsx}", "await import(filePath)"],
+  // importRouteModule(): dev-mode route module load. resolveRouteChain() only
+  // calls it when no `registry` is provided; registry mode uses pickRouteModule
+  // (a plain Record lookup, no import).
+  "layout.ts": ["await import(filePath)"],
+};
+
+async function serverFiles(): Promise<string[]> {
+  const glob = new Bun.Glob("**/*.ts");
+  const out: string[] = [];
+  for await (const rel of glob.scan(SERVER_DIR)) out.push(rel);
+  return out.sort();
+}
+
+// A dynamic import whose argument is NOT a single string literal. We allow
+//   import("./literal.ts")   import('../x.ts')
+// and reject
+//   import(filePath)   import(`${x}`)   import(someVar)
+const VARIABLE_IMPORT_RE = /\bimport\(\s*(?!["'])/;
+const STRING_LITERAL_IMPORT_RE = /\bimport\(\s*["'][^"']+["']\s*\)/;
+
+// Return the executable (non-comment) lines of a source file.
+//
+// We deliberately avoid regex comment-stripping over the whole file: glob
+// patterns and route literals contain comment-terminator and slash sequences
+// inside string literals, and a naive block-comment regex spans across them
+// and corrupts real code (e.g. swallowing a later `import(filePath)`),
+// producing false negatives. A line-oriented filter is coarse but safe for our
+// purpose — detecting `import(...)` / `Bun.Glob` constructs, which never
+// legitimately begin inside a doc-comment block in this codebase.
+function codeLines(src: string): string[] {
+  const out: string[] = [];
+  let inBlock = false;
+  for (const raw of src.split("\n")) {
+    const line = raw;
+    const trimmed = line.trim();
+    if (inBlock) {
+      if (trimmed.includes("*/")) inBlock = false;
+      continue;
+    }
+    // Whole-line block comment open without close on the same line.
+    if (trimmed.startsWith("/*") && !trimmed.includes("*/")) { inBlock = true; continue; }
+    if (trimmed.startsWith("*") || trimmed.startsWith("//")) continue;
+    out.push(line);
+  }
+  return out;
+}
+
+/** A line carries a runtime dynamic import with a non-literal argument. */
+function hasVariableImport(line: string): boolean {
+  // Ignore type-position imports like `import("bun").BunPlugin`.
+  const cleaned = line.replace(/import\(\s*["'][^"']+["']\s*\)\s*\./g, "TYPE.");
+  return VARIABLE_IMPORT_RE.test(cleaned);
+}
+
+describe("compile-safety: server path is single-binary compatible", () => {
+  test("no Bun.Glob/.scan() on the server path outside dev-fallback functions", async () => {
+    const files = await serverFiles();
+    const violations: string[] = [];
+
+    for (const rel of files) {
+      // Use the RAW source here: glob patterns like "**/*.{tsx,ts}" contain a
+      // literal `*/` that a naive comment-stripper would mistake for a comment
+      // terminator and corrupt the string.
+      const src = await Bun.file(resolve(SERVER_DIR, rel)).text();
+      if (!/new Bun\.Glob|\.scan\(/.test(src)) continue;
+      const allowed = ALLOWED[rel] ?? [];
+      // Accept only if the file's glob usage matches an allowlisted pattern.
+      const ok = allowed.some((a) => src.includes(a));
+      if (!ok) violations.push(rel);
+    }
+
+    expect(violations).toEqual([]);
+  });
+
+  test("no variable (non-literal) dynamic import() on the server path outside dev-fallback functions", async () => {
+    const files = await serverFiles();
+    const violations: string[] = [];
+
+    for (const rel of files) {
+      const lines = codeLines(await Bun.file(resolve(SERVER_DIR, rel)).text());
+      const offending = lines.filter(hasVariableImport);
+      if (offending.length === 0) continue;
+      const allowed = ALLOWED[rel] ?? [];
+      // Every offending line must match an allowlisted dev-fallback construct.
+      const ok = offending.every((line) => allowed.some((a) => line.includes(a)));
+      if (!ok) violations.push(`${rel}: ${offending.map((l) => l.trim()).join(" | ")}`);
+    }
+
+    expect(violations).toEqual([]);
+  });
+
+  test("self-check: the allowlisted files really do still contain their guarded constructs", async () => {
+    // Guards against the allowlist going stale (e.g. a file is refactored so the
+    // construct moves, leaving a dead allowlist entry that would mask a future
+    // real violation in that file).
+    for (const [rel, needles] of Object.entries(ALLOWED)) {
+      const src = await Bun.file(resolve(SERVER_DIR, rel)).text();
+      for (const needle of needles) {
+        expect(src.includes(needle)).toBe(true);
+      }
+    }
+  });
+
+  test("serve.ts dynamic imports are all string literals (traceable by bun build --compile)", async () => {
+    const lines = codeLines(await Bun.file(resolve(SERVER_DIR, "serve.ts")).text());
+    for (const line of lines) {
+      // Skip type-position imports like `import("bun").BunPlugin[]`.
+      const cleaned = line.replace(/import\(\s*["'][^"']+["']\s*\)\s*[.[]/g, "TYPE");
+      if (!/\bimport\(/.test(cleaned)) continue;
+      // Any remaining runtime import( on this line must be a string literal.
+      expect(line).toMatch(STRING_LITERAL_IMPORT_RE);
+    }
+  });
+});

package/src/__tests__/compile-smoke.test.ts

@@ -0,0 +1,276 @@
+/**
+ * End-to-end guardrail for the `bun build --compile` single-executable feature.
+ *
+ * This test runs the REAL single-binary pipeline against a minimal app and
+ * boots the produced executable:
+ *
+ *   writeModuleRegistries()  → app/_generated/{routes,actions}.ts (static imports)
+ *   runBuild()               → build/client/* + route-manifest.json
+ *   writeManifestModule()    → app/_generated/manifest.ts (inline constant)
+ *   bun build --compile      → a self-contained binary (no runtime fs scans)
+ *
+ * It then launches the binary and asserts the SSR response is correct —
+ * crucially that the route's `meta()` <title>/<meta> tags render into the HTML
+ * (the recently-added SSR meta path) and that `__BRACTJS_DATA__` is present.
+ * This converts "we believe it still compiles" into "CI proves the binary
+ * boots and serves correct HTML."
+ *
+ * It mirrors the CLI's `compile` command (bin/cli.ts) but drives the exported
+ * programmatic functions directly so it stays in-process and fast to author.
+ *
+ * The whole suite is skipped gracefully if `bun build --compile` isn't usable
+ * in the current environment (it is intentionally heavyweight).
+ */
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import {
+  writeModuleRegistries,
+  writeManifestModule,
+} from "../codegen/module-registry.ts";
+import { runBuild } from "../build/bundler.ts";
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+// Inside the repo tree so the app's `@bractjs/bractjs` import resolves to the
+// in-repo framework (the package self-resolves its own name). `.tmp-*` is
+// gitignored, so the working tree stays clean even if a run aborts.
+const TMP = resolve(import.meta.dir, `.tmp-compile-${Date.now()}`);
+const APP = join(TMP, "app");
+const BIN = join(TMP, "bin", "app");
+const PORT = 3987;
+
+let compileAvailable = false;
+let serverProc: Bun.Subprocess | null = null;
+const originalCwd = process.cwd();
+
+// Probe once: can we run `bun build --compile` at all here?
+async function probeCompile(): Promise<boolean> {
+  const dir = join(TMP, ".probe");
+  await mkdir(dir, { recursive: true });
+  const entry = join(dir, "entry.ts");
+  const out = join(dir, "out");
+  await writeFile(entry, `console.log("ok");\n`);
+  try {
+    const proc = Bun.spawn(["bun", "build", "--compile", entry, "--outfile", out], {
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return (await proc.exited) === 0;
+  } catch {
+    return false;
+  }
+}
+
+async function scaffoldApp(): Promise<void> {
+  await mkdir(join(APP, "routes"), { recursive: true });
+  await mkdir(join(TMP, "bin"), { recursive: true });
+
+  await writeFile(
+    join(APP, "root.tsx"),
+    `import { Outlet, Scripts } from "@bractjs/bractjs";
+export default function Root() {
+  return (
+    <html lang="en">
+      <head><meta charSet="utf-8" /></head>
+      <body><Outlet /><Scripts /></body>
+    </html>
+  );
+}
+`,
+  );
+
+  await writeFile(
+    join(APP, "routes", "_index.tsx"),
+    `import type { LoaderArgs } from "@bractjs/bractjs";
+export function loader(_args: LoaderArgs) {
+  return { greeting: "compiled-hello" };
+}
+export function meta() {
+  return [
+    { title: "Compiled Title" },
+    { name: "description", content: "Compiled description" },
+  ];
+}
+export default function Index() {
+  return <main>index</main>;
+}
+`,
+  );
+
+  await writeFile(
+    join(APP, "server.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 ?? ${PORT}),
+  appDir: "./app",
+  publicDir: "./public",
+  manifest,
+  routeFiles,
+  moduleRegistry,
+  actionModules,
+});
+`,
+  );
+
+  // tsconfig so --compile-autoload-tsconfig picks up the JSX runtime, mirroring
+  // the scaffold template.
+  await writeFile(
+    join(TMP, "tsconfig.json"),
+    JSON.stringify(
+      {
+        compilerOptions: {
+          target: "ESNext",
+          module: "ESNext",
+          moduleResolution: "bundler",
+          lib: ["ESNext", "DOM", "DOM.Iterable"],
+          jsx: "react-jsx",
+          jsxImportSource: "react",
+          strict: true,
+          allowImportingTsExtensions: true,
+          noEmit: true,
+          skipLibCheck: true,
+        },
+      },
+      null,
+      2,
+    ),
+  );
+
+  await mkdir(join(TMP, "public"), { recursive: true });
+}
+
+// `stdout`/`stderr` are typed as `number | ReadableStream` on a Bun
+// Subprocess (the number branch is for inherited/ignored fds). Only read when
+// it's an actual stream.
+async function readStream(s: number | ReadableStream<Uint8Array> | undefined | null): Promise<string> {
+  if (!s || typeof s === "number") return "";
+  return new Response(s).text();
+}
+
+async function waitForServer(url: string, timeoutMs = 15_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status === 404) return true;
+    } catch {
+      // not up yet
+    }
+    await Bun.sleep(150);
+  }
+  return false;
+}
+
+beforeAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+  await mkdir(TMP, { recursive: true });
+  compileAvailable = await probeCompile();
+  if (!compileAvailable) {
+    console.warn("[compile-smoke] `bun build --compile` unavailable — skipping e2e binary test.");
+    return;
+  }
+
+  await scaffoldApp();
+
+  // Run the pipeline from inside the app dir (runBuild + manifest use cwd-relative
+  // `build/` paths, matching how the CLI runs).
+  process.chdir(TMP);
+  try {
+    // A) static registries for routes + actions
+    await writeModuleRegistries(resolve(TMP, "app"));
+    // B) client + server bundle (writes build/client + route-manifest.json)
+    await runBuild({ appDir: "./app", buildDir: "./build" });
+    // C) snapshot manifest → app/_generated/manifest.ts
+    await writeManifestModule(resolve(TMP, "app"), resolve(TMP, "build"));
+
+    // D) bun build --compile (mirror bin/cli.ts: dev NODE_ENV avoids the React
+    // TSX jsxDEV miscompile; --compile-autoload-tsconfig keeps JSX settings).
+    const compile = Bun.spawn(
+      [
+        "bun",
+        "build",
+        "--compile",
+        "--compile-autoload-tsconfig",
+        "app/server.ts",
+        "--outfile",
+        BIN,
+      ],
+      {
+        cwd: TMP,
+        env: { ...process.env, NODE_ENV: "development" },
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const code = await compile.exited;
+    if (code !== 0) {
+      const err = await readStream(compile.stderr);
+      throw new Error(`bun build --compile failed (${code}):\n${err}`);
+    }
+
+    // Boot the binary (NODE_ENV=production so dev gates stay off — the real
+    // single-binary deployment mode).
+    serverProc = Bun.spawn([BIN], {
+      cwd: TMP,
+      env: { ...process.env, NODE_ENV: "production", PORT: String(PORT) },
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    const up = await waitForServer(`http://localhost:${PORT}/`);
+    if (!up) {
+      const err = await readStream(serverProc.stderr);
+      throw new Error(`compiled binary did not start listening:\n${err}`);
+    }
+  } finally {
+    process.chdir(originalCwd);
+  }
+}, 120_000);
+
+afterAll(async () => {
+  try { serverProc?.kill(); } catch { /* already dead */ }
+  process.chdir(originalCwd);
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("bun build --compile single-binary", () => {
+  test("compiled binary serves SSR HTML with 200", async () => {
+    if (!compileAvailable) return;
+    const res = await fetch(`http://localhost:${PORT}/`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("text/html");
+  });
+
+  test("compiled binary renders meta() <title> and <meta> into the SSR head", async () => {
+    if (!compileAvailable) return;
+    const res = await fetch(`http://localhost:${PORT}/`);
+    const html = await res.text();
+    // Strip the data island so we assert on the rendered document, not the
+    // __BRACTJS_DATA__ JSON (which also carries the meta text).
+    const withoutScripts = html.replace(/<script[\s\S]*?<\/script>/g, "");
+    expect(withoutScripts).toMatch(/<title>Compiled Title<\/title>/);
+    expect(withoutScripts).toMatch(/<meta[^>]+name="description"[^>]+content="Compiled description"/);
+  });
+
+  test("compiled binary embeds loader data + bootstrap island", async () => {
+    if (!compileAvailable) return;
+    const res = await fetch(`http://localhost:${PORT}/`);
+    const html = await res.text();
+    expect(html).toContain("__BRACTJS_DATA__");
+    expect(html).toContain("compiled-hello");
+  });
+
+  test("compiled binary did not fall back to a runtime fs scan (registry mode)", async () => {
+    if (!compileAvailable) return;
+    // A 404 for an unmapped path proves routing came from the embedded trie,
+    // not a crash from a missing appDir scan.
+    const res = await fetch(`http://localhost:${PORT}/definitely-not-a-route`);
+    expect(res.status).toBe(404);
+  });
+});
+
+// Keep REPO_ROOT referenced (documents where framework resolution comes from).
+void REPO_ROOT;

package/src/__tests__/csp.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe } from "bun:test";
+import { csp, getCspNonce, CSP_NONCE_KEY } from "../server/csp.ts";
+import { MiddlewarePipeline, type MiddlewareContext } from "../server/middleware.ts";
+import { renderRoute } from "../server/render.ts";
+
+async function runCsp(
+  mw: ReturnType<typeof csp>,
+  handler: (ctx: MiddlewareContext) => Promise<Response>,
+): Promise<{ res: Response; ctx: MiddlewareContext }> {
+  const ctx: MiddlewareContext = { request: new Request("http://x/"), params: {}, context: {} };
+  const pipeline = new MiddlewarePipeline();
+  pipeline.use(mw);
+  const res = await pipeline.run(ctx, () => handler(ctx));
+  return { res, ctx };
+}
+
+describe("csp middleware", () => {
+  test("sets Content-Security-Policy header with a script-src nonce", async () => {
+    const { res, ctx } = await runCsp(csp(), () => Promise.resolve(new Response("ok")));
+    const policy = res.headers.get("Content-Security-Policy");
+    expect(policy).toBeTruthy();
+    const nonce = getCspNonce(ctx.context);
+    expect(nonce).toBeTruthy();
+    expect(policy).toContain(`'nonce-${nonce}'`);
+    expect(policy).toContain("default-src 'self'");
+  });
+
+  test("stashes the nonce on the context under CSP_NONCE_KEY", async () => {
+    const { ctx } = await runCsp(csp(), () => Promise.resolve(new Response("ok")));
+    expect(typeof ctx.context[CSP_NONCE_KEY]).toBe("string");
+  });
+
+  test("generates a fresh nonce per request", async () => {
+    const a = await runCsp(csp(), () => Promise.resolve(new Response("ok")));
+    const b = await runCsp(csp(), () => Promise.resolve(new Response("ok")));
+    expect(getCspNonce(a.ctx.context)).not.toBe(getCspNonce(b.ctx.context));
+  });
+
+  test("custom directives override/extend the defaults", async () => {
+    const { res } = await runCsp(
+      csp({ directives: { "img-src": "'self' https://cdn.example", "frame-ancestors": "'none'" } }),
+      () => Promise.resolve(new Response("ok")),
+    );
+    const policy = res.headers.get("Content-Security-Policy")!;
+    expect(policy).toContain("img-src 'self' https://cdn.example");
+    expect(policy).toContain("frame-ancestors 'none'");
+  });
+
+  test("a null directive value removes that directive", async () => {
+    const { res } = await runCsp(
+      csp({ directives: { "object-src": null } }),
+      () => Promise.resolve(new Response("ok")),
+    );
+    expect(res.headers.get("Content-Security-Policy")).not.toContain("object-src");
+  });
+
+  test("reportOnly emits the report-only header instead", async () => {
+    const { res } = await runCsp(csp({ reportOnly: true }), () => Promise.resolve(new Response("ok")));
+    expect(res.headers.get("Content-Security-Policy-Report-Only")).toBeTruthy();
+    expect(res.headers.get("Content-Security-Policy")).toBeNull();
+  });
+});
+
+describe("csp + render", () => {
+  test("renderRoute stamps the nonce onto the inline bootstrap script", async () => {
+    const res = await renderRoute({
+      shell: null,
+      loaderData: {},
+      actionData: null,
+      params: {},
+      pathname: "/",
+      manifest: { clientEntry: "/build/client/client.js", routes: {} },
+      meta: [],
+      nonce: "test-nonce-123",
+    });
+    const html = await res.text();
+    // The inline bootstrap script React emits should carry our nonce.
+    expect(html).toMatch(/<script[^>]*nonce="test-nonce-123"/);
+  });
+});

package/src/__tests__/fixtures/app/routes/_index.tsx

@@ -5,9 +5,13 @@ export function loader() {
   return { message: "hello from bractjs" };
 }
 
-// Meta returns a title descriptor
+// Meta returns a title + description descriptor
 export function meta() {
-  return [{ title: "BractJS Test Home" }];
+  return [
+    { title: "BractJS Test Home" },
+    { name: "description", content: "Bract test description" },
+    { property: "og:title", content: "Bract OG Title" },
+  ];
 }
 
 // Action echoes the submitted form field

package/src/__tests__/fixtures/app/routes/protected.tsx

@@ -0,0 +1,15 @@
+// Fixture for the /_data auth-parity test. beforeLoad() is the contract point
+// where auth must live: it runs for BOTH full-page GET and the /_data soft-nav
+// JSON endpoint, so a route gated here cannot leak loader data via /_data.
+export function beforeLoad(): Response {
+  return new Response("Forbidden", { status: 403 });
+}
+
+export function loader() {
+  // Must never reach the client — beforeLoad short-circuits first.
+  return { secret: "TOP-SECRET-LOADER-DATA" };
+}
+
+export default function Protected() {
+  return <p>protected</p>;
+}