@bractjs/bractjs 0.1.26 → 0.1.28

package/src/__tests__/search-validation.test.ts

@@ -0,0 +1,125 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { searchParamsToObject, validateSearch } from "../server/search.ts";
+import { createServer } from "../server/serve.ts";
+
+// ── Unit: searchParamsToObject ──────────────────────────────────────────────
+
+describe("searchParamsToObject", () => {
+  test("single values stay strings", () => {
+    expect(searchParamsToObject(new URLSearchParams("a=1&b=x"))).toEqual({ a: "1", b: "x" });
+  });
+
+  test("repeated keys collapse into arrays", () => {
+    expect(searchParamsToObject(new URLSearchParams("tag=a&tag=b&tag=c"))).toEqual({
+      tag: ["a", "b", "c"],
+    });
+  });
+
+  test("empty params → empty object", () => {
+    expect(searchParamsToObject(new URLSearchParams(""))).toEqual({});
+  });
+});
+
+// ── Unit: validateSearch ────────────────────────────────────────────────────
+
+const coercingSchema = {
+  safeParse(input: unknown) {
+    const obj = input as Record<string, unknown>;
+    const n = Number(obj.page ?? 1);
+    if (!Number.isInteger(n)) {
+      return { success: false, error: { issues: [{ path: ["page"], message: "not an int" }] } };
+    }
+    return { success: true, data: { page: n } };
+  },
+};
+
+describe("validateSearch", () => {
+  test("no schema → raw string record (back-compat)", async () => {
+    const url = new URL("http://x.test/posts?page=2&tag=a&tag=b");
+    expect(await validateSearch(undefined, url)).toEqual({ page: "2", tag: ["a", "b"] });
+  });
+
+  test("schema output replaces raw strings (coercion)", async () => {
+    const url = new URL("http://x.test/posts?page=7");
+    expect(await validateSearch(coercingSchema, url)).toEqual({ page: 7 });
+  });
+
+  test("schema failure throws a 400 Response with field errors", async () => {
+    const url = new URL("http://x.test/posts?page=abc");
+    try {
+      await validateSearch(coercingSchema, url);
+      expect.unreachable("validateSearch should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Response);
+      const res = err as Response;
+      expect(res.status).toBe(400);
+      const body = (await res.json()) as { errors: Record<string, string[]> };
+      expect(body.errors.page).toEqual(["not an int"]);
+    }
+  });
+});
+
+// ── Integration: live server with a searchSchema route ─────────────────────
+
+const PORT = 3996;
+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();
+});
+
+describe("searchSchema end-to-end", () => {
+  test("/_data returns the validated+coerced search object and loaders receive it", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo?page=3&tag=x")}`);
+    expect(res.status).toBe(200);
+    const data = (await res.json()) as {
+      search: Record<string, unknown>;
+      route: { receivedSearch: Record<string, unknown> };
+    };
+    expect(data.search).toEqual({ page: 3, tag: ["x"] });
+    expect(data.route.receivedSearch).toEqual({ page: 3, tag: ["x"] });
+  });
+
+  test("/_data applies schema defaults when params are absent", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo")}`);
+    const data = (await res.json()) as { search: Record<string, unknown> };
+    expect(data.search).toEqual({ page: 1 });
+  });
+
+  test("/_data with invalid search → 400 with field errors, loader never runs", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/search-demo?page=abc")}`);
+    expect(res.status).toBe(400);
+    const body = (await res.json()) as { errors: Record<string, string[]> };
+    expect(body.errors.page).toBeDefined();
+  });
+
+  test("document GET with invalid search → 400", async () => {
+    const res = await fetch(`${BASE}/search-demo?page=abc`);
+    expect(res.status).toBe(400);
+  });
+
+  test("document GET hydrates the validated search into __BRACTJS_DATA__", async () => {
+    const res = await fetch(`${BASE}/search-demo?page=5`);
+    expect(res.status).toBe(200);
+    const html = await res.text();
+    expect(html).toContain('"search":{"page":5}');
+  });
+
+  test("routes without a schema still get the raw string record", async () => {
+    const res = await fetch(`${BASE}/_data?path=${encodeURIComponent("/?q=hello")}`);
+    const data = (await res.json()) as { search: Record<string, unknown> };
+    expect(data.search).toEqual({ q: "hello" });
+  });
+});

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

@@ -0,0 +1,239 @@
+/**
+ * Type-level guardrail for end-to-end typed routing.
+ *
+ * The runtime helpers (`<Link>`, `useNavigate`, `useParams`, `useSearchParams`)
+ * gain their type-safety from a declaration-merging seam: `bractjs codegen`
+ * augments the package's `Register` interface, and the helpers resolve route
+ * types from it. None of that is observable at runtime — only `tsc` proves it.
+ * This test writes a fixture, generates its `route-types.gen.ts`, and runs
+ * `tsc --noEmit` over:
+ *
+ *   - positive usage (typed <Link>/useNavigate/useParams must compile), and
+ *   - negative usage guarded by `@ts-expect-error` (bad params/routes MUST error,
+ *     so a directive that goes unused fails the build), and
+ *   - a SECOND fixture with NO codegen, proving un-registered apps still compile
+ *     with the loose `string` fallback (the backwards-compat contract).
+ *
+ * It guards the subtle failure mode that nearly shipped: a too-clever resolution
+ * type silently falling back to loose `string`, which compiles but enforces
+ * nothing.
+ *
+ * The fixture lives inside the repo (`.tmp-types-*`, gitignored) so its
+ * `@bractjs/bractjs` import self-resolves to the in-repo framework via the root
+ * tsconfig `paths` mapping.
+ */
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { generateRouteTypes } from "../codegen/route-codegen.ts";
+
+const REPO_ROOT = resolve(import.meta.dir, "../..");
+const TMP = resolve(import.meta.dir, `.tmp-types-${Date.now()}`);
+
+// Invoke TypeScript via `bunx tsc` — it works whether tsc is installed locally
+// or fetched on demand. (A direct node_modules/.bin/tsc path is unreliable here:
+// it may be a dangling symlink to an un-installed package.)
+const TSC_CMD = ["bunx", "tsc"] as const;
+
+// A fixture tsconfig that resolves `@bractjs/bractjs` → the in-repo entry, mirrors
+// the example apps' compiler options, and type-checks only this fixture's files.
+function tsconfig(includeGlobDir: string): string {
+  return JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ESNext",
+        module: "ESNext",
+        moduleResolution: "bundler",
+        lib: ["ESNext", "DOM", "DOM.Iterable"],
+        jsx: "react-jsx",
+        jsxImportSource: "react",
+        strict: true,
+        noEmit: true,
+        skipLibCheck: true,
+        allowImportingTsExtensions: true,
+        types: ["react", "react-dom"],
+        // `paths` with absolute targets needs no `baseUrl` (and baseUrl is
+        // deprecated as of TS6, which would fail the compile here).
+        paths: { "@bractjs/bractjs": [join(REPO_ROOT, "src/index.ts")] },
+      },
+      include: [join(includeGlobDir, "**/*.ts"), join(includeGlobDir, "**/*.tsx")],
+    },
+    null,
+    2,
+  );
+}
+
+async function runTsc(projectDir: string): Promise<{ code: number; output: string }> {
+  const proc = Bun.spawn([...TSC_CMD, "--noEmit", "-p", join(projectDir, "tsconfig.json")], {
+    cwd: projectDir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  return { code, output: stdout + stderr };
+}
+
+let tscAvailable = false;
+
+beforeAll(async () => {
+  await mkdir(TMP, { recursive: true });
+  // Real availability probe: actually run the compiler. Earlier this checked a
+  // symlink's existence and silently skipped when it dangled — making the whole
+  // suite a no-op that still "passed". Run `tsc --version` and trust the exit.
+  try {
+    const probe = Bun.spawn([...TSC_CMD, "--version"], { stdout: "pipe", stderr: "pipe" });
+    const out = await new Response(probe.stdout).text();
+    tscAvailable = (await probe.exited) === 0 && /Version/.test(out);
+  } catch {
+    tscAvailable = false;
+  }
+});
+
+afterAll(async () => {
+  await rm(TMP, { recursive: true, force: true });
+});
+
+describe("typed routing (type-level)", () => {
+  test("tsc is available (else the type-level assertions below are skipped)", () => {
+    // Surfaced as its own test so a skipped type-check is visible in the report
+    // rather than masquerading as a silent pass.
+    if (!tscAvailable) console.warn("[typed-routing] tsc unavailable — type-level checks skipped");
+    expect(typeof tscAvailable).toBe("boolean");
+  });
+
+  test("registered app: typed Link/useNavigate/useParams compile; bad usage errors", async () => {
+    if (!tscAvailable) return; // tsc not available in this environment — skip gracefully
+
+    const app = join(TMP, "registered");
+    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));
+    await writeFile(join(app, "tsconfig.json"), tsconfig("."));
+
+    await writeFile(
+      join(app, "usage.tsx"),
+      `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` +
+        `    }}>go</button>\n` +
+        `    {/* @ts-expect-error /blog/:id has no \`nope\` param */}\n` +
+        `    <span>{p.nope}</span>\n` +
+        `  </>);\n` +
+        `}\n`,
+    );
+
+    const { code, output } = await runTsc(app);
+    // Exit 0 means: positives compiled AND every @ts-expect-error was satisfied
+    // by a real error. A silently-loose type would leave directives unused → TS2578.
+    // (`output` may carry bunx "Resolving dependencies" noise — key on TS errors.)
+    expect(output).not.toContain("TS2578"); // unused @ts-expect-error → typing too loose
+    expect(output).not.toMatch(/error TS/);
+    expect(code).toBe(0);
+  }, 60_000);
+
+  test("un-registered app (no codegen): loose string fallback still compiles", async () => {
+    if (!tscAvailable) return;
+
+    const app = join(TMP, "loose");
+    await mkdir(app, { recursive: true });
+    await writeFile(join(app, "tsconfig.json"), tsconfig("."));
+    // No route-types.gen.ts → Register stays empty → everything falls back to string.
+    await writeFile(
+      join(app, "usage.tsx"),
+      `import { Link, useNavigate, useParams } from "@bractjs/bractjs";\n` +
+        `export function App({ href }: { href: string }) {\n` +
+        `  const navigate = useNavigate();\n` +
+        `  const p = useParams();\n` +
+        `  return (<>\n` +
+        `    <Link to={href}>any string</Link>\n` +
+        `    <Link to="/anything/at/all">arbitrary literal</Link>\n` +
+        `    <button onClick={() => { void navigate("/wherever"); }}>{p.x}</button>\n` +
+        `  </>);\n` +
+        `}\n`,
+    );
+
+    const { code, output } = await runTsc(app);
+    expect(output).not.toMatch(/error TS/);
+    expect(code).toBe(0);
+  }, 60_000);
+});