@bractjs/bractjs 0.1.27 → 0.1.29

package/src/__tests__/security-fixes.test.ts

@@ -0,0 +1,201 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { createServer } from "../server/serve.ts";
+import { pipeline } from "../server/middleware.ts";
+import { route, handleApiRequest } from "../server/api-route.ts";
+import { csp } from "../server/csp.ts";
+import { hasForbiddenKey, nullProtoFromEntries } from "../server/proto-guard.ts";
+import { searchParamsToObject } from "../server/search.ts";
+import { validate } from "../server/validate.ts";
+import { resolve } from "node:path";
+
+const PORT = 3989;
+const BASE = `http://localhost:${PORT}`;
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+
+// A marker middleware on the GLOBAL pipeline + a CSP middleware, plus a couple
+// of API routes. Registered before the server starts; cleared afterwards so
+// these don't leak into other suites sharing the process.
+const MARKER = "X-Test-Global-MW";
+
+let handle: ReturnType<typeof createServer>;
+
+beforeAll(() => {
+  pipeline.clear();
+  pipeline.use(async (_ctx, next) => {
+    const res = await next();
+    res.headers.set(MARKER, "1");
+    return res;
+  });
+  pipeline.use(csp());
+
+  // Protected-by-default mutating route, an opted-out one, and a GET.
+  route("POST", "/api/secure", (input: unknown) => ({ ok: true, input }));
+  route("POST", "/api/public", (input: unknown) => ({ ok: true, input }), { csrf: false });
+  route("GET", "/api/ping", () => ({ pong: true }));
+
+  handle = createServer({
+    port: PORT,
+    appDir: FIXTURE_APP,
+    manifest: { clientEntry: "/build/client/client.js", routes: {} },
+  });
+});
+
+afterAll(() => {
+  handle.stop();
+  pipeline.clear();
+});
+
+// ── H-1 — global middleware now wraps the special endpoints ────────────────
+
+describe("H-1: global middleware covers special endpoints", () => {
+  test("marker + CSP applied to an /api response", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    expect(res.headers.get("Content-Security-Policy")).toContain("default-src 'self'");
+  });
+
+  test("marker applied to /_action (even on 404 unknown id)", async () => {
+    const res = await fetch(`${BASE}/_action?id=deadbeefdeadbeef`, {
+      method: "POST",
+      headers: { "X-BractJS-Action": "1", "Content-Type": "application/json" },
+      body: "[]",
+    });
+    // unknown id → 404, but it still passed through the global pipeline.
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to /_image (even on 400 bad request)", async () => {
+    const res = await fetch(`${BASE}/_image?src=/etc/passwd`);
+    expect(res.headers.get(MARKER)).toBe("1");
+  });
+
+  test("marker applied to a normal SSR document too (no double-run)", async () => {
+    const res = await fetch(`${BASE}/`);
+    expect(res.headers.get(MARKER)).toBe("1");
+    // CSP header present exactly once.
+    expect(res.headers.get("Content-Security-Policy")).toContain("script-src");
+  });
+});
+
+// ── H-2 — CSRF on typed /api routes ────────────────────────────────────────
+
+describe("H-2: /api CSRF protection", () => {
+  test("cross-site POST to a protected route → 403", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(403);
+  });
+
+  test("no-attribution POST (no Origin / no header / no Sec-Fetch-Site) → 403", async () => {
+    // Call the handler directly so no Origin is auto-added by fetch.
+    const req = new Request("http://localhost/api/secure", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    const res = await handleApiRequest(req);
+    expect(res?.status).toBe(403);
+  });
+
+  test("same-origin POST (X-BractJS-Action) to a protected route → 200", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: JSON.stringify({ a: 1 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 1 } });
+  });
+
+  test("same-origin POST via Sec-Fetch-Site → 200 (no custom header needed)", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "same-origin" },
+      body: JSON.stringify({ a: 2 }),
+    });
+    expect(res.status).toBe(200);
+  });
+
+  test("opted-out route (csrf:false) allows cross-site POST", async () => {
+    const res = await fetch(`${BASE}/api/public`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "Sec-Fetch-Site": "cross-site" },
+      body: JSON.stringify({ a: 3 }),
+    });
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, input: { a: 3 } });
+  });
+
+  test("GET /api is never CSRF-gated", async () => {
+    const res = await fetch(`${BASE}/api/ping`, { headers: { "Sec-Fetch-Site": "cross-site" } });
+    expect(res.status).toBe(200);
+  });
+
+  test("forbidden-key JSON body to an /api route → 400", async () => {
+    const res = await fetch(`${BASE}/api/secure`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", "X-BractJS-Action": "1" },
+      body: '{"__proto__":{"polluted":true}}',
+    });
+    expect(res.status).toBe(400);
+    // And Object.prototype was not polluted.
+    expect(({} as Record<string, unknown>).polluted).toBeUndefined();
+  });
+});
+
+// ── M-1 — CSP form-action ──────────────────────────────────────────────────
+
+describe("M-1: CSP defaults", () => {
+  test("default policy includes form-action 'self'", async () => {
+    const res = await fetch(`${BASE}/api/ping`);
+    expect(res.headers.get("Content-Security-Policy")).toContain("form-action 'self'");
+  });
+});
+
+// ── M-2 — prototype-pollution guards ───────────────────────────────────────
+
+describe("M-2: proto-guard", () => {
+  test("hasForbiddenKey detects buried __proto__", () => {
+    let v: unknown = JSON.parse('{"__proto__":{"x":1}}');
+    for (let i = 0; i < 5; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("hasForbiddenKey passes a clean object", () => {
+    expect(hasForbiddenKey({ a: { b: { c: 1 } } })).toBe(false);
+  });
+
+  test("hasForbiddenKey fails closed past the scan depth", () => {
+    let v: unknown = { value: "x" };
+    for (let i = 0; i < 250; i++) v = { a: v };
+    expect(hasForbiddenKey(v)).toBe(true);
+  });
+
+  test("searchParamsToObject yields a null-prototype object", () => {
+    const out = searchParamsToObject(new URLSearchParams("__proto__=evil&a=1"));
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    // __proto__ lands as a real own key, not a prototype mutation.
+    expect(out["__proto__"]).toBe("evil");
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+  });
+
+  test("validate() over FormData with a __proto__ field does not pollute", async () => {
+    const fd = new FormData();
+    fd.set("__proto__", "evil");
+    fd.set("name", "ok");
+    // Identity schema — just returns what it gets.
+    const schema = { parse: (x: unknown) => x };
+    const out = (await validate(schema, fd)) as Record<string, unknown>;
+    expect(({} as Record<string, unknown>).evil).toBeUndefined();
+    expect(out.name).toBe("ok");
+  });
+
+  test("nullProtoFromEntries builds a null-prototype object", () => {
+    const out = nullProtoFromEntries([["__proto__", 1], ["a", 2]]);
+    expect(Object.getPrototypeOf(out)).toBeNull();
+    expect(out["a"]).toBe(2);
+  });
+});

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/__tests__/use-matches.test.ts

@@ -0,0 +1,54 @@
+import { test, expect, describe } from "bun:test";
+import { buildMatches } from "../server/matches.ts";
+import type { LayoutChain } from "../server/layout.ts";
+import type { LoaderResults } from "../server/loader.ts";
+
+describe("buildMatches", () => {
+  test("returns root → layouts → route in order with ids and data", () => {
+    const chain: LayoutChain = {
+      root: { handle: { breadcrumb: "Home" } },
+      layouts: [{ handle: { breadcrumb: "Blog" } }],
+      route: { handle: { breadcrumb: "Post" } },
+      files: { root: "root.tsx", layouts: ["routes/blog/layout.tsx"], route: "routes/blog/[id].tsx" },
+    };
+    const data: LoaderResults = { root: { user: "a" }, layouts: [{ posts: 2 }], route: { id: "7" } };
+
+    const matches = buildMatches(chain, data, { id: "7" }, "/blog/7");
+
+    expect(matches.map((m) => m.id)).toEqual([
+      "root.tsx",
+      "routes/blog/layout.tsx",
+      "routes/blog/[id].tsx",
+    ]);
+    expect(matches.map((m) => m.handle?.breadcrumb)).toEqual(["Home", "Blog", "Post"]);
+    expect(matches[2].data).toEqual({ id: "7" });
+    expect(matches[1].data).toEqual({ posts: 2 });
+    // params + pathname shared across the chain.
+    expect(matches.every((m) => m.pathname === "/blog/7")).toBe(true);
+    expect(matches.every((m) => m.params.id === "7")).toBe(true);
+  });
+
+  test("handle is undefined when a module does not export it", () => {
+    const chain: LayoutChain = {
+      root: {},
+      layouts: [],
+      route: { handle: { title: "x" } },
+      files: { root: "root.tsx", layouts: [], route: "routes/_index.tsx" },
+    };
+    const data: LoaderResults = { root: null, layouts: [], route: null };
+    const matches = buildMatches(chain, data, {}, "/");
+    expect(matches[0].handle).toBeUndefined();
+    expect(matches[1].handle).toEqual({ title: "x" });
+  });
+
+  test("falls back to synthetic ids when files metadata is absent", () => {
+    const chain: LayoutChain = {
+      root: {},
+      layouts: [{}],
+      route: {},
+    };
+    const data: LoaderResults = { root: null, layouts: [null], route: null };
+    const matches = buildMatches(chain, data, {}, "/x");
+    expect(matches.map((m) => m.id)).toEqual(["root", "layout:0", "route"]);
+  });
+});