@bractjs/bractjs 0.1.27 → 0.1.29

package/bin/cli.ts

@@ -43,6 +43,10 @@ async function scaffoldNew(appName: string): Promise<void> {
   try {
     const { writeModuleRegistries } = await import("../src/codegen/module-registry.ts");
     await writeModuleRegistries(join(appDir, "app"));
+    // Generate typed routes so the scaffold has working <Link>/useParams typing
+    // out of the box (no manual `bractjs codegen` step before first dev run).
+    const { writeRouteTypes } = await import("../src/codegen/route-codegen.ts");
+    await writeRouteTypes(join(appDir, "app"));
     // Manifest stub — overwritten by `bractjs codegen:manifest` after a build
     const stubManifest = [
       "// Stub manifest — replaced by `bractjs codegen:manifest` after running",
@@ -101,6 +105,16 @@ switch (command) {
     const { loadUserConfig } = await import("../src/config/load.ts");
     const userCfg = await loadUserConfig();
     await runBuild({ appDir: "./app", buildDir: "./build", ...userCfg });
+    if (userCfg.prerender) {
+      const { runPrerender } = await import("../src/build/prerender.ts");
+      const { written } = await runPrerender({
+        prerender: userCfg.prerender,
+        appDir: userCfg.appDir ?? "./app",
+        publicDir: userCfg.publicDir,
+        buildDir: userCfg.buildDir ?? "./build",
+      });
+      console.log(`[bract] prerender → ${written.length} files`);
+    }
     break;
   }
 
@@ -109,7 +123,10 @@ switch (command) {
     // output. Users can still override with `NODE_ENV=staging bractjs start`.
     if (!process.env.NODE_ENV) process.env.NODE_ENV = "production";
     const { createServer } = await import("../src/server/serve.ts");
-    createServer({ port: 3000, buildDir: "./build" });
+    const { loadUserConfig } = await import("../src/config/load.ts");
+    // The config carries runtime-relevant fields too (ssr, port, dirs).
+    const userCfg = await loadUserConfig();
+    createServer({ port: 3000, buildDir: "./build", ...userCfg });
     break;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bractjs/bractjs",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "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",
@@ -45,7 +45,8 @@
   "scripts": {
     "dev": "bun run src/dev/server.ts",
     "build": "bun run src/build/bundler.ts",
-    "test": "bun test"
+    "test": "bun test",
+    "typecheck": "bunx tsc --noEmit"
   },
   "peerDependencies": {
     "react": "^19",

package/src/__tests__/codegen-write.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe, beforeEach, afterEach } from "bun:test";
+import { mkdir, rm, writeFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import {
+  writeRouteTypes,
+  explainStalenessForApp,
+} from "../codegen/route-codegen.ts";
+
+let appDir = "";
+
+beforeEach(async () => {
+  appDir = join(tmpdir(), `bract-codegen-write-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await mkdir(join(appDir, "routes"), { recursive: true });
+  await writeFile(join(appDir, "routes", "_index.tsx"), "export default () => null;");
+});
+
+afterEach(async () => {
+  await rm(appDir, { recursive: true, force: true });
+});
+
+describe("writeRouteTypes — idempotency", () => {
+  test("writes on first run, skips identical re-run, rewrites on route change", async () => {
+    const first = await writeRouteTypes(appDir);
+    expect(first.written).toBe(true);
+
+    const destStat = await stat(first.dest);
+    const mtime1 = destStat.mtimeMs;
+
+    // Identical re-run: no write (so no file-watcher event / editor reload loop).
+    const second = await writeRouteTypes(appDir);
+    expect(second.written).toBe(false);
+    expect((await stat(first.dest)).mtimeMs).toBe(mtime1);
+
+    // Add a route → content changes → write happens.
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    const third = await writeRouteTypes(appDir);
+    expect(third.written).toBe(true);
+  });
+});
+
+describe("explainStalenessForApp", () => {
+  test("missing generated file → reason mentions missing", async () => {
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/missing/);
+  });
+
+  test("fresh after codegen → null", async () => {
+    await writeRouteTypes(appDir);
+    expect(await explainStalenessForApp(appDir)).toBeNull();
+  });
+
+  test("added route → reports +1", async () => {
+    await writeRouteTypes(appDir);
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/\+1 added/);
+  });
+
+  test("removed route → reports -1", async () => {
+    await writeFile(join(appDir, "routes", "about.tsx"), "export default () => null;");
+    await writeRouteTypes(appDir);
+    await rm(join(appDir, "routes", "about.tsx"));
+    const reason = await explainStalenessForApp(appDir);
+    expect(reason).toMatch(/-1 removed/);
+  });
+});

package/src/__tests__/codegen.test.ts

@@ -2,7 +2,11 @@ import { test, expect, describe, beforeAll, afterAll } from "bun:test";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { generateRouteTypes } from "../codegen/route-codegen.ts";
+import {
+  generateRouteTypes,
+  routesFingerprint,
+  readFingerprint,
+} from "../codegen/route-codegen.ts";
 
 let appDir = "";
 
@@ -29,6 +33,23 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/\| "\/users\/:id"/);
   });
 
+  test("emits a fingerprint matching routesFingerprint, and is deterministic", async () => {
+    const out = await generateRouteTypes(appDir);
+    // Header carries the route fingerprint.
+    const embedded = readFingerprint(out);
+    expect(embedded).toMatch(/^[0-9a-f]+$/);
+    expect(embedded).toBe(await routesFingerprint(["/", "/users/:id"]));
+    // Same input → byte-identical output (order-independent / reproducible).
+    expect(await generateRouteTypes(appDir)).toBe(out);
+    // Pattern union is sorted (deterministic across filesystems).
+    expect(out.indexOf('| "/"')).toBeLessThan(out.indexOf('| "/users/:id"'));
+  });
+
+  test("routesFingerprint is order-independent", async () => {
+    expect(await routesFingerprint(["/a", "/b"])).toBe(await routesFingerprint(["/b", "/a"]));
+    expect(await routesFingerprint(["/a"])).not.toBe(await routesFingerprint(["/a", "/b"]));
+  });
+
   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 });
@@ -45,7 +66,7 @@ describe("route-codegen — output shape", () => {
     // 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"');
+    expect(out).toContain('import type { RouteSearchParamsMap, RouteContextMap, InferSchemaOutput } from "@bractjs/bractjs"');
 
     // The Register seam carries the route union and a per-route params map.
     expect(out).toContain("interface Register {");
@@ -53,6 +74,12 @@ describe("route-codegen — output shape", () => {
     expect(out).toMatch(/"\/users\/:id": \{ id: string \};/); // dynamic route → typed params
     expect(out).toMatch(/"\/about": \{\};/);                   // static route → no params
 
+    // Schema-inferred search shapes: a per-route map derived from each route
+    // module's `searchSchema` export, registered under `searchOutput`.
+    expect(out).toContain("export type GeneratedSearchOutput = {");
+    expect(out).toContain('typeof import("./routes/about.tsx") extends { searchSchema: infer S }');
+    expect(out).toContain("searchOutput: GeneratedSearchOutput;");
+
     await rm(regApp, { recursive: true, force: true });
   });
 

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

@@ -51,6 +51,10 @@ const ALLOWED: Record<string, string[]> = {
   // calls it when no `registry` is provided; registry mode uses pickRouteModule
   // (a plain Record lookup, no import).
   "layout.ts": ["await import(filePath)"],
+  // renderSpaShell(): source-mode root.tsx load for the SPA shell. Compiled
+  // binaries always pass a moduleRegistry, which takes the registry branch
+  // (plain Record lookup) before this import is reached.
+  "spa.ts": ["await import(rootPath)"],
 };
 
 async function serverFiles(): Promise<string[]> {

package/src/__tests__/csp.test.ts

@@ -54,6 +54,16 @@ describe("csp middleware", () => {
     expect(res.headers.get("Content-Security-Policy")).not.toContain("object-src");
   });
 
+  test("default style-src allows 'unsafe-inline'; strict drops it", async () => {
+    const def = await runCsp(csp(), () => Promise.resolve(new Response("ok")));
+    expect(def.res.headers.get("Content-Security-Policy")).toContain("style-src 'self' 'unsafe-inline'");
+
+    const strict = await runCsp(csp({ strict: true }), () => Promise.resolve(new Response("ok")));
+    const policy = strict.res.headers.get("Content-Security-Policy")!;
+    expect(policy).toContain("style-src 'self'");
+    expect(policy).not.toContain("'unsafe-inline'");
+  });
+
   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();

package/src/__tests__/define-actions.test.ts

@@ -0,0 +1,69 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import { defineActions } from "../shared/define-actions.ts";
+import type { ActionArgs } from "../shared/route-types.ts";
+
+function argsWith(intent?: string, extra: Record<string, string> = {}): ActionArgs {
+  const fd = new FormData();
+  if (intent !== undefined) fd.set("intent", intent);
+  for (const [k, v] of Object.entries(extra)) fd.set(k, v);
+  return {
+    request: new Request("http://localhost/"),
+    params: {},
+    context: {},
+    search: {},
+    formData: fd,
+  };
+}
+
+const ORIGINAL_ENV = Bun.env.NODE_ENV;
+afterEach(() => {
+  if (ORIGINAL_ENV === undefined) delete Bun.env.NODE_ENV;
+  else Bun.env.NODE_ENV = ORIGINAL_ENV;
+});
+
+describe("defineActions", () => {
+  test("dispatches to the matching handler with full args", async () => {
+    let seen: ActionArgs | null = null;
+    const action = defineActions({
+      add: (args) => { seen = args; return { ok: true, who: "add" }; },
+      remove: () => ({ ok: true, who: "remove" }),
+    });
+    const result = await action(argsWith("add", { title: "x" }));
+    expect(result).toEqual({ ok: true, who: "add" });
+    expect(seen!.formData.get("title")).toBe("x");
+  });
+
+  test("unknown intent → 400 listing known intents in dev", async () => {
+    Bun.env.NODE_ENV = "development";
+    const action = defineActions({ add: () => ({}), remove: () => ({}) });
+    const res = await action(argsWith("nope"));
+    expect(res).toBeInstanceOf(Response);
+    expect((res as Response).status).toBe(400);
+    const body = await (res as Response).json() as { error: string };
+    expect(body.error).toContain("add");
+    expect(body.error).toContain("remove");
+    expect(body.error).toContain("nope");
+  });
+
+  test("unknown intent → terse 400 in production", async () => {
+    Bun.env.NODE_ENV = "production";
+    const action = defineActions({ add: () => ({}) });
+    const res = await action(argsWith("nope")) as Response;
+    expect(res.status).toBe(400);
+    const body = await res.json() as { error: string };
+    expect(body.error).toBe("Unknown action intent.");
+  });
+
+  test("missing intent → 400", async () => {
+    const action = defineActions({ add: () => ({}) });
+    const res = await action(argsWith(undefined)) as Response;
+    expect(res.status).toBe(400);
+  });
+
+  test("awaits async handlers", async () => {
+    const action = defineActions({
+      slow: async () => { await Promise.resolve(); return { done: true }; },
+    });
+    expect(await action(argsWith("slow"))).toEqual({ done: true });
+  });
+});

package/src/__tests__/env.test.ts

@@ -45,6 +45,24 @@ describe("safeStringify", () => {
     expect(parsed.self).toBe("[Circular]");
   });
 
+  // Regression: a SHARED (non-cyclic) reference must serialize normally. The
+  // old WeakSet-of-everything approach flagged the second occurrence as
+  // circular — which corrupted __BRACTJS_DATA__ whenever a loader echoed
+  // `args.search` (also present at the payload's top level).
+  test("shared references are not flagged as circular", () => {
+    const shared = { page: 5 };
+    const out = safeStringify({ a: shared, b: { inner: shared } });
+    expect(JSON.parse(out)).toEqual({ a: { page: 5 }, b: { inner: { page: 5 } } });
+  });
+
+  test("deep cycles through arrays are still caught", () => {
+    const arr: unknown[] = [];
+    const obj = { arr };
+    arr.push(obj);
+    const parsed = JSON.parse(safeStringify(obj)) as { arr: string[] };
+    expect(parsed.arr[0]).toBe("[Circular]");
+  });
+
   test("handles nested objects", () => {
     const out = safeStringify({ a: { b: { c: 42 } } });
     expect(JSON.parse(out)).toEqual({ a: { b: { c: 42 } } });

package/src/__tests__/fetcher-store.test.ts

@@ -0,0 +1,67 @@
+import { test, expect, describe } from "bun:test";
+import { fetcherStore, EMPTY_FETCHERS } from "../client/fetcher-store.ts";
+
+// The store is a module-level singleton — use unique keys per test so cases
+// stay independent.
+
+describe("fetcherStore", () => {
+  test("update creates an entry with idle defaults merged", () => {
+    fetcherStore.update("t1", { state: "submitting", formMethod: "POST" });
+    const entry = fetcherStore.get("t1");
+    expect(entry).toEqual({
+      key: "t1",
+      state: "submitting",
+      data: undefined,
+      formMethod: "POST",
+    });
+    fetcherStore.remove("t1");
+  });
+
+  test("partial updates preserve other fields", () => {
+    fetcherStore.update("t2", { state: "submitting", formMethod: "DELETE" });
+    fetcherStore.update("t2", { data: { ok: true } });
+    const entry = fetcherStore.get("t2")!;
+    expect(entry.state).toBe("submitting");
+    expect(entry.formMethod).toBe("DELETE");
+    expect(entry.data).toEqual({ ok: true });
+    fetcherStore.remove("t2");
+  });
+
+  test("subscribe fires on update and remove; unsubscribe stops it", () => {
+    let calls = 0;
+    const unsub = fetcherStore.subscribe(() => calls++);
+    fetcherStore.update("t3", { state: "loading" });
+    expect(calls).toBe(1);
+    fetcherStore.remove("t3");
+    expect(calls).toBe(2);
+    unsub();
+    fetcherStore.update("t3b", { state: "loading" });
+    expect(calls).toBe(2);
+    fetcherStore.remove("t3b");
+  });
+
+  test("removing a missing key does not notify", () => {
+    let calls = 0;
+    const unsub = fetcherStore.subscribe(() => calls++);
+    fetcherStore.remove("never-existed");
+    expect(calls).toBe(0);
+    unsub();
+  });
+
+  test("snapshot is referentially stable between updates (useSyncExternalStore contract)", () => {
+    fetcherStore.update("t4", { state: "idle" });
+    const a = fetcherStore.getSnapshot();
+    const b = fetcherStore.getSnapshot();
+    expect(a).toBe(b);
+    fetcherStore.update("t4", { state: "loading" });
+    const c = fetcherStore.getSnapshot();
+    expect(c).not.toBe(a);
+    expect(c.find((e) => e.key === "t4")?.state).toBe("loading");
+    fetcherStore.remove("t4");
+  });
+
+  test("EMPTY_FETCHERS is a stable empty server snapshot", () => {
+    expect(EMPTY_FETCHERS).toEqual([]);
+    expect(EMPTY_FETCHERS).toBe(EMPTY_FETCHERS);
+  });
+});

package/src/__tests__/fixtures/app/root.tsx

@@ -1,9 +1,14 @@
-// Minimal root component for integration tests.
+// Minimal root component for integration tests. Renders the matched route
+// through <Outlet/> so body-level SSR assertions (components, Fallbacks) work.
+import { Outlet } from "../../../client/components/Outlet.tsx";
+
 export default function Root() {
   return (
     <html>
       <head></head>
-      <body></body>
+      <body>
+        <Outlet />
+      </body>
     </html>
   );
 }

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

@@ -0,0 +1,9 @@
+// A route whose loader throws a plain Error — for asserting that the failure is
+// reported with the route file's location (in dev) rather than anonymously.
+export function loader() {
+  throw new Error("kaboom from loader");
+}
+
+export default function Boom() {
+  return <p>unreachable — loader throws</p>;
+}

package/src/__tests__/fixtures/app/routes/client-only.tsx

@@ -0,0 +1,16 @@
+// Selective SSR: `ssr: false` — the loader must NOT run during document SSR
+// and the Fallback must render in the component's place. The client completes
+// the render via /_data after hydration.
+export const ssr = false;
+
+export function loader() {
+  return { secret: "CLIENT-ONLY-LOADER-DATA" };
+}
+
+export function Fallback() {
+  return <p>client-only fallback</p>;
+}
+
+export default function ClientOnlyPage() {
+  return <p>client-only component</p>;
+}

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

@@ -0,0 +1,16 @@
+// Module-level mutable state so tests can prove the submit → revalidate
+// contract: a mutation changes what the loader returns on the next /_data.
+let count = 0;
+
+export function loader() {
+  return { count };
+}
+
+export async function action() {
+  count++;
+  return { ok: true, count };
+}
+
+export default function CounterPage() {
+  return <p>counter</p>;
+}

package/src/__tests__/fixtures/app/routes/data-only.tsx

@@ -0,0 +1,16 @@
+// Selective SSR: `ssr: "data-only"` — loaders DO run during document SSR (the
+// data ships in the bootstrap payload), but the component renders only on the
+// client; the Fallback SSRs in its place.
+export const ssr = "data-only";
+
+export function loader() {
+  return { payload: "DATA-ONLY-LOADER-DATA" };
+}
+
+export function Fallback() {
+  return <p>data-only fallback</p>;
+}
+
+export default function DataOnlyPage() {
+  return <p>data-only component</p>;
+}

package/src/__tests__/fixtures/app/routes/features-demo.tsx

@@ -0,0 +1,28 @@
+// Fixture exercising the Phase 1/2/4 route exports end-to-end:
+//   - `headers`  → Cache-Control on the document + /_data response
+//   - `handle`   → surfaced via useMatches() (asserted from the payload)
+//   - `middleware` → sets context (read by the loader) and stamps a header
+import type { RouteMiddlewareFunction, HeadersArgs } from "../../../../shared/route-types.ts";
+
+const setUser: RouteMiddlewareFunction = async (ctx, next) => {
+  ctx.context.demoUser = "alice";
+  const res = await next();
+  res.headers.set("X-Demo-Mw", "1");
+  return res;
+};
+
+export const middleware = [setUser];
+
+export const handle = { breadcrumb: "Features" };
+
+export function loader({ context }: { context: Record<string, unknown> }) {
+  return { user: context.demoUser ?? null };
+}
+
+export function headers(_args: HeadersArgs) {
+  return { "Cache-Control": "public, max-age=120" };
+}
+
+export default function FeaturesDemo() {
+  return <p>features</p>;
+}

package/src/__tests__/fixtures/app/routes/intent-demo.tsx

@@ -0,0 +1,46 @@
+// Exercises defineActions + <Form intent> + safeValidate end to end.
+import { defineActions, safeValidate, formText } from "../../../../index.ts";
+import { Form } from "../../../../client/components/Form.tsx";
+import type { Schema } from "../../../../server/validate.ts";
+
+const TitleSchema: Schema<{ title: string }> = {
+  safeParse(input: unknown) {
+    const t = typeof (input as { title?: unknown })?.title === "string"
+      ? ((input as { title: string }).title).trim()
+      : "";
+    return t
+      ? { success: true, data: { title: t } }
+      : { success: false, error: { issues: [{ path: ["title"], message: "Title required" }] } };
+  },
+};
+
+let count = 0;
+
+export function loader() {
+  return { count };
+}
+
+export const action = defineActions({
+  add: async ({ formData }) => {
+    const r = await safeValidate(TitleSchema, formData);
+    if (!r.ok) return { error: r.firstError };
+    count++;
+    return { ok: true, title: r.data.title, count };
+  },
+  remove: ({ formData }) => {
+    formText(formData, "id"); // exercise the helper
+    if (count > 0) count--;
+    return { ok: true, count };
+  },
+});
+
+export default function IntentDemo() {
+  return (
+    <main>
+      <Form intent="add">
+        <input name="title" />
+        <button type="submit">Add</button>
+      </Form>
+    </main>
+  );
+}

package/src/__tests__/fixtures/app/routes/protected-client-only.tsx

@@ -0,0 +1,15 @@
+// Security invariant: `ssr: false` must NOT skip beforeLoad — it is the auth
+// gate, and it runs for document GETs and /_data alike regardless of SSR mode.
+export const ssr = false;
+
+export function beforeLoad() {
+  return new Response("Forbidden", { status: 403 });
+}
+
+export function loader() {
+  return { secret: "GATED-CLIENT-ONLY-DATA" };
+}
+
+export default function ProtectedClientOnlyPage() {
+  return <p>protected client-only</p>;
+}

package/src/__tests__/fixtures/app/routes/search-demo.tsx

@@ -0,0 +1,39 @@
+import type { LoaderArgs } from "../../../../shared/route-types.ts";
+
+// Hand-rolled Zod-compatible schema (the repo has no zod dependency): coerces
+// `page` to a positive integer defaulting to 1; passes `tag` through as an
+// array. Mirrors what `z.object({ page: z.coerce.number().int().positive()
+// .default(1), tag: z.array(z.string()).optional() })` would do.
+export const searchSchema = {
+  safeParse(input: unknown) {
+    const obj = (input ?? {}) as Record<string, unknown>;
+    const issues: Array<{ path: (string | number)[]; message: string }> = [];
+
+    let page = 1;
+    if (obj.page !== undefined) {
+      const n = Number(obj.page);
+      if (!Number.isInteger(n) || n < 1) {
+        issues.push({ path: ["page"], message: "page must be a positive integer" });
+      } else {
+        page = n;
+      }
+    }
+
+    if (issues.length > 0) return { success: false, error: { issues } };
+
+    const data: Record<string, unknown> = { page };
+    if (typeof obj.tag === "string") data.tag = [obj.tag];
+    else if (Array.isArray(obj.tag)) data.tag = obj.tag;
+    return { success: true, data };
+  },
+};
+
+// Echo the validated search object so tests can assert loaders receive the
+// coerced shape, not raw strings.
+export function loader({ search }: LoaderArgs) {
+  return { receivedSearch: search };
+}
+
+export default function SearchDemoPage() {
+  return <p>search demo</p>;
+}

package/src/__tests__/form-data-helpers.test.ts

@@ -0,0 +1,43 @@
+import { test, expect, describe } from "bun:test";
+import { formText, formValues } from "../shared/form-data.ts";
+
+describe("formText", () => {
+  test("returns the string value", () => {
+    const fd = new FormData();
+    fd.set("id", "42");
+    expect(formText(fd, "id")).toBe("42");
+  });
+
+  test('returns "" for a missing key', () => {
+    expect(formText(new FormData(), "nope")).toBe("");
+  });
+
+  test('returns "" for a File value', () => {
+    const fd = new FormData();
+    fd.set("upload", new File(["x"], "a.txt"));
+    expect(formText(fd, "upload")).toBe("");
+  });
+});
+
+describe("formValues", () => {
+  test("collects all string entries (skips files)", () => {
+    const fd = new FormData();
+    fd.set("a", "1");
+    fd.set("b", "2");
+    fd.set("file", new File(["x"], "a.txt"));
+    expect(formValues(fd)).toEqual({ a: "1", b: "2" });
+  });
+
+  test("first occurrence wins for repeated keys", () => {
+    const fd = new FormData();
+    fd.append("tag", "one");
+    fd.append("tag", "two");
+    expect(formValues(fd)).toEqual({ tag: "one" });
+  });
+
+  test("named subset defaults missing keys to ''", () => {
+    const fd = new FormData();
+    fd.set("title", "Hello");
+    expect(formValues(fd, ["title", "body"])).toEqual({ title: "Hello", body: "" });
+  });
+});