@bractjs/bractjs 0.1.27 → 0.1.29

package/src/__tests__/headers.test.ts

@@ -0,0 +1,111 @@
+import { test, expect, describe } from "bun:test";
+import { resolveHeaders, applyRouteHeaders } from "../server/headers.ts";
+import type { LayoutChain } from "../server/layout.ts";
+import type { LoaderResults } from "../server/loader.ts";
+import type { HeadersFunction } from "../shared/route-types.ts";
+
+const params = {};
+const req = new Request("http://localhost/");
+
+function chain(parts: {
+  root?: HeadersFunction;
+  layouts?: (HeadersFunction | undefined)[];
+  route?: HeadersFunction;
+}): LayoutChain {
+  return {
+    root: parts.root ? { headers: parts.root } : {},
+    layouts: (parts.layouts ?? []).map((h) => (h ? { headers: h } : {})),
+    route: parts.route ? { headers: parts.route } : {},
+  };
+}
+
+function results(over: Partial<LoaderResults> = {}): LoaderResults {
+  return { root: null, layouts: [], route: null, ...over };
+}
+
+describe("resolveHeaders", () => {
+  test("returns null when no module exports headers", () => {
+    expect(resolveHeaders(chain({}), results(), params, req)).toBeNull();
+  });
+
+  test("collects a single route's headers", () => {
+    const merged = resolveHeaders(
+      chain({ route: () => ({ "Cache-Control": "max-age=60" }) }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+  });
+
+  test("innermost route wins per key (route over root)", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0", Vary: "Cookie" }),
+        route: () => ({ "Cache-Control": "max-age=300" }),
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=300");
+    // Root-only key survives.
+    expect(merged?.get("Vary")).toBe("Cookie");
+  });
+
+  test("parentHeaders carries accumulated values to inner links", () => {
+    let seen: string | null = "unset";
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "X-From-Root": "1" }),
+        route: ({ parentHeaders }) => {
+          seen = parentHeaders.get("X-From-Root");
+          return {};
+        },
+      }),
+      results(),
+      params,
+      req,
+    );
+    expect(seen).toBe("1");
+    expect(merged?.get("X-From-Root")).toBe("1");
+  });
+
+  test("passes the matching loaderData slice to each link", () => {
+    const merged = resolveHeaders(
+      chain({ route: ({ loaderData }) => ({ ETag: String((loaderData as { etag: string }).etag) }) }),
+      results({ route: { etag: "abc" } }),
+      params,
+      req,
+    );
+    expect(merged?.get("ETag")).toBe("abc");
+  });
+
+  test("layout headers merge between root and route", () => {
+    const merged = resolveHeaders(
+      chain({
+        root: () => ({ "Cache-Control": "max-age=0" }),
+        layouts: [() => ({ "Cache-Control": "max-age=10", Vary: "Accept" })],
+        route: () => ({ "Cache-Control": "max-age=60" }),
+      }),
+      results({ layouts: [null] }),
+      params,
+      req,
+    );
+    expect(merged?.get("Cache-Control")).toBe("max-age=60");
+    expect(merged?.get("Vary")).toBe("Accept");
+  });
+});
+
+describe("applyRouteHeaders", () => {
+  test("overrides same-key defaults and is a no-op for null", () => {
+    const base = new Headers({ "Cache-Control": "no-store", "X-Base": "1" });
+    applyRouteHeaders(base, new Headers({ "Cache-Control": "max-age=60" }));
+    expect(base.get("Cache-Control")).toBe("max-age=60");
+    expect(base.get("X-Base")).toBe("1");
+
+    const base2 = new Headers({ "X-Base": "1" });
+    applyRouteHeaders(base2, null);
+    expect(base2.get("X-Base")).toBe("1");
+  });
+});

package/src/__tests__/integration.test.ts

@@ -34,6 +34,16 @@ test("GET /_data?path=/ returns JSON with route key", async () => {
   expect(data).toHaveProperty("params");
 });
 
+// Regression: soft navigation reads `meta` from the /_data payload to update
+// the document head — when the payload omitted it, every soft-nav wiped the
+// title/description back to nothing.
+test("GET /_data?path=/ includes the route's merged meta", async () => {
+  const res = await fetch(`${BASE}/_data?path=/`);
+  const data = (await res.json()) as { meta?: Array<Record<string, string>> };
+  expect(Array.isArray(data.meta)).toBe(true);
+  expect(data.meta).toContainEqual({ title: "BractJS Test Home" });
+});
+
 test("POST / runs action and returns 200 HTML", async () => {
   const form = new FormData();
   form.set("name", "bract");
@@ -72,6 +82,52 @@ test("GET /nonexistent returns 404", async () => {
   expect(res.status).toBe(404);
 });
 
+// defineActions: dispatch on the form's `intent` field through one route action.
+test("defineActions dispatches POST intent=add to the right handler", async () => {
+  const form = new FormData();
+  form.set("intent", "add");
+  form.set("title", "Buy milk");
+  const res = await fetch(`${BASE}/intent-demo`, {
+    method: "POST",
+    body: form,
+    headers: { Origin: BASE, "X-BractJS-Action": "1" },
+  });
+  expect(res.status).toBe(200);
+  const data = (await res.json()) as { ok?: boolean; title?: string };
+  expect(data.ok).toBe(true);
+  expect(data.title).toBe("Buy milk");
+});
+
+test("defineActions returns 400 for an unknown intent", async () => {
+  const form = new FormData();
+  form.set("intent", "bogus");
+  const res = await fetch(`${BASE}/intent-demo`, {
+    method: "POST",
+    body: form,
+    headers: { Origin: BASE, "X-BractJS-Action": "1" },
+  });
+  expect(res.status).toBe(400);
+});
+
+// <Form intent="add"> renders the hidden input server-side (no DOM harness:
+// assert on the SSR HTML directly).
+test("<Form intent> renders the hidden intent input in SSR HTML", async () => {
+  const res = await fetch(`${BASE}/intent-demo`);
+  const html = await res.text();
+  expect(html).toContain('name="intent"');
+  expect(html).toContain('value="add"');
+});
+
+// A loader that throws is isolated into the route's __error slot (not a 500),
+// so layout/root still render. (The dev-only `routeFile` field is covered as a
+// unit in loader.test.ts; this server runs in prod mode.)
+test("a throwing loader is captured in the route slot's __error", async () => {
+  const res = await fetch(`${BASE}/_data?path=/boom`);
+  expect(res.status).toBe(200);
+  const data = (await res.json()) as { route: { __error?: { message: string } } };
+  expect(data.route.__error).toBeDefined();
+});
+
 test("HTML includes window.__BRACTJS_DATA__", async () => {
   const res = await fetch(`${BASE}/`);
   const html = await res.text();
@@ -126,3 +182,37 @@ test("/_data of a beforeLoad-gated route is blocked and never leaks loader data"
   const body = await res.text();
   expect(body).not.toContain("TOP-SECRET-LOADER-DATA");
 });
+
+// ── Route headers / useMatches / nested middleware (Phases 1, 2, 4) ──────────
+
+test("route `headers` export sets Cache-Control on the document response", async () => {
+  const res = await fetch(`${BASE}/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  // Baseline hardening headers still present (not clobbered).
+  expect(res.headers.get("X-Content-Type-Options")).toBe("nosniff");
+});
+
+test("route `headers` export also applies to the /_data response", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.status).toBe(200);
+  expect(res.headers.get("Cache-Control")).toBe("public, max-age=120");
+  expect(res.headers.get("content-type")).toContain("application/json");
+});
+
+test("nested middleware runs (sets context read by the loader, stamps a header)", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  expect(res.headers.get("X-Demo-Mw")).toBe("1");
+  const data = (await res.json()) as { route?: { user?: string } };
+  // The loader saw the context value the middleware set.
+  expect(data.route?.user).toBe("alice");
+});
+
+test("/_data payload carries the matched chain (useMatches) with handle", async () => {
+  const res = await fetch(`${BASE}/_data?path=/features-demo`);
+  const data = (await res.json()) as { matches?: Array<{ id: string; handle?: { breadcrumb?: string } }> };
+  expect(Array.isArray(data.matches)).toBe(true);
+  // Leaf route carries its handle export.
+  const leaf = data.matches!.at(-1)!;
+  expect(leaf.handle?.breadcrumb).toBe("Features");
+});

package/src/__tests__/layout-registry.test.ts

@@ -58,13 +58,17 @@ describe("resolveLayoutChainFromRegistry", () => {
     expect(r.layoutFiles).toEqual([]);
   });
 
-  test("matches sibling-dir layouts only when route is deeper", () => {
-    // urlPattern "blog" → layoutDirs returns [] (no ancestor)
+  test("wraps a folder index in that folder's layout", () => {
+    // routes/blog/_index.tsx (URL /blog) lives inside routes/blog/, so the
+    // sibling routes/blog/layout.tsx wraps it — matching Remix/RR/Next, where
+    // an index is nested under its directory's layout. Layout dirs are derived
+    // from the FILE path, so the `_index` → `blog` urlPattern collapse no
+    // longer hides the ancestor directory.
     const r = resolveLayoutChainFromRegistry(
       { filePath: "routes/blog/_index.tsx", urlPattern: "blog", segments: ["blog"] },
       registry,
     );
-    expect(r.layoutFiles).toEqual(["root.tsx"]);
+    expect(r.layoutFiles).toEqual(["root.tsx", "routes/blog/layout.tsx"]);
   });
 });
 

package/src/__tests__/loader.test.ts

@@ -1,4 +1,4 @@
-import { test, expect, describe } from "bun:test";
+import { test, expect, describe, spyOn } from "bun:test";
 import { safeRun, runLoaders, buildLoaderArgs } from "../server/loader.ts";
 import { HttpError } from "../shared/errors.ts";
 import type { LoaderArgs } from "../shared/route-types.ts";
@@ -9,6 +9,7 @@ const stubArgs: LoaderArgs = {
   request: new Request("http://localhost/"),
   params: {},
   context: {},
+  search: {},
 };
 
 const emptyModule: RouteModule = {};
@@ -41,6 +42,36 @@ describe("safeRun", () => {
     const fn = async () => { throw new Response(null, { status: 302, headers: { Location: "/" } }); };
     await expect(safeRun(fn, stubArgs)).rejects.toBeInstanceOf(Response);
   });
+
+  test("includes the `where` location in the error log", async () => {
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await safeRun(async () => { throw new Error("boom"); }, stubArgs, undefined, "routes/x.tsx");
+      const logged = spy.mock.calls.map((c) => String(c[0])).join("\n");
+      expect(logged).toContain("loader error in routes/x.tsx");
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  test("dev __error carries the routeFile; prod stays generic", async () => {
+    const original = Bun.env.NODE_ENV;
+    const spy = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      Bun.env.NODE_ENV = "development";
+      const dev = await safeRun(async () => { throw new Error("boom"); }, stubArgs, undefined, "routes/x.tsx");
+      expect(dev).toMatchObject({ __error: { routeFile: "routes/x.tsx" } });
+
+      Bun.env.NODE_ENV = "production";
+      const prod = await safeRun(async () => { throw new Error("boom"); }, stubArgs, undefined, "routes/x.tsx") as { __error: Record<string, unknown> };
+      expect(prod.__error.routeFile).toBeUndefined();
+      expect(prod.__error.message).toBe("Internal Server Error");
+    } finally {
+      if (original === undefined) delete Bun.env.NODE_ENV;
+      else Bun.env.NODE_ENV = original;
+      spy.mockRestore();
+    }
+  });
 });
 
 describe("runLoaders", () => {

package/src/__tests__/matcher.test.ts

@@ -67,3 +67,32 @@ describe("matchRoute", () => {
     expect(r2?.params.id).toBe("123");
   });
 });
+
+describe("optional segments [[id]]", () => {
+  test("matches with the segment present (binds the param)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users/42", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({ id: "42" });
+  });
+
+  test("matches with the segment absent (param unset)", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]")]);
+    const r = matchRoute("/users", trie);
+    expect(r).not.toBeNull();
+    expect(r?.params).toEqual({});
+  });
+
+  test("static sibling still wins over the optional param", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/me")]);
+    const r = matchRoute("/users/me", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/me");
+  });
+
+  test("does not over-consume — extra segment falls through to catch-all", () => {
+    const trie = buildTrie([makeRoute("users/[[id]]"), makeRoute("users/[...rest]")]);
+    const r = matchRoute("/users/1/2", trie);
+    expect(r?.routeFile.urlPattern).toBe("users/[...rest]");
+    expect(r?.params.rest).toBe("1/2");
+  });
+});

package/src/__tests__/module-registry.test.ts

@@ -18,9 +18,8 @@ beforeAll(async () => {
   await writeFile(join(TMP, "root.tsx"), `export default function Root() { return null; }\n`);
   await writeFile(join(TMP, "routes", "_index.tsx"), `export default function Home() { return null; }\n`);
   await writeFile(join(TMP, "routes", "blog", "layout.tsx"), `export default function L({ children }: any) { return children; }\n`);
-  // Nested route — `routes/blog/layout.tsx` only applies because there is a
-  // deeper route under /blog/. Layouts wrap children, not the leaf at the
-  // same path level (matches `layout.ts`'s `layoutDirs` resolution).
+  // Nested route under /blog/ — `routes/blog/layout.tsx` wraps everything in
+  // its directory (including a `blog/_index`), per `layoutDirsFromFilePath`.
   await writeFile(join(TMP, "routes", "blog", "[slug].tsx"), `export default function P() { return null; }\n`);
 
   await writeFile(

package/src/__tests__/nav-utils.test.ts

@@ -0,0 +1,46 @@
+import { test, expect, describe } from "bun:test";
+import { parseTo, createLocationKey } from "../client/nav-utils.ts";
+
+describe("parseTo", () => {
+  test("plain pathname", () => {
+    expect(parseTo("/posts")).toEqual({ pathname: "/posts", search: "", hash: "" });
+  });
+
+  test("pathname + search", () => {
+    expect(parseTo("/posts?page=2")).toEqual({ pathname: "/posts", search: "?page=2", hash: "" });
+  });
+
+  test("pathname + hash", () => {
+    expect(parseTo("/docs#install")).toEqual({ pathname: "/docs", search: "", hash: "#install" });
+  });
+
+  test("pathname + search + hash", () => {
+    expect(parseTo("/docs?v=2#install")).toEqual({ pathname: "/docs", search: "?v=2", hash: "#install" });
+  });
+
+  test("hash containing a question mark stays in the hash", () => {
+    expect(parseTo("/docs#frag?notsearch")).toEqual({ pathname: "/docs", search: "", hash: "#frag?notsearch" });
+  });
+
+  test("empty string falls back to root", () => {
+    expect(parseTo("")).toEqual({ pathname: "/", search: "", hash: "" });
+  });
+
+  test("bare query string keeps root pathname", () => {
+    expect(parseTo("?page=2")).toEqual({ pathname: "/", search: "?page=2", hash: "" });
+  });
+
+  test("root with everything", () => {
+    expect(parseTo("/?a=1&b=2#top")).toEqual({ pathname: "/", search: "?a=1&b=2", hash: "#top" });
+  });
+});
+
+describe("createLocationKey", () => {
+  test("returns a short non-empty string and varies between calls", () => {
+    const a = createLocationKey();
+    const b = createLocationKey();
+    expect(a.length).toBeGreaterThanOrEqual(6);
+    expect(a.length).toBeLessThanOrEqual(10);
+    expect(a).not.toBe(b);
+  });
+});

package/src/__tests__/prerender.test.ts

@@ -0,0 +1,102 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve, join } from "node:path";
+import { tmpdir } from "node:os";
+import { rm } from "node:fs/promises";
+import { runPrerender, prerenderPaths } from "../build/prerender.ts";
+import { createServer } from "../server/serve.ts";
+
+const FIXTURE_APP = resolve(import.meta.dir, "fixtures/app");
+const TMP_BUILD = join(tmpdir(), `bract-prerender-${Date.now()}`);
+const MANIFEST = { clientEntry: "/build/client/client.js", routes: {} };
+
+// ── Unit: path mapping + safety ─────────────────────────────────────────────
+
+describe("prerenderPaths", () => {
+  test("maps / and nested paths to index.html + _data.json", () => {
+    expect(prerenderPaths("/")).toEqual({ html: "index.html", data: "_data.json" });
+    expect(prerenderPaths("/about")).toEqual({ html: "about/index.html", data: "about/_data.json" });
+    expect(prerenderPaths("/blog/intro")).toEqual({ html: "blog/intro/index.html", data: "blog/intro/_data.json" });
+  });
+
+  test("rejects route patterns instead of silently writing junk", () => {
+    expect(() => prerenderPaths("/blog/:slug")).toThrow(/PATTERN/);
+    expect(() => prerenderPaths("/blog/[slug]")).toThrow(/PATTERN/);
+    expect(() => prerenderPaths("relative")).toThrow(/must start/);
+  });
+
+  test("rejects dot segments — these strings become filesystem writes", () => {
+    expect(() => prerenderPaths("/../etc/passwd")).toThrow(/dot segments/);
+    expect(() => prerenderPaths("/a/./b")).toThrow(/dot segments/);
+  });
+});
+
+// ── Integration: generate + serve ───────────────────────────────────────────
+
+describe("runPrerender + production serving", () => {
+  let handle: ReturnType<typeof createServer>;
+  const PORT = 3992;
+  const BASE = `http://localhost:${PORT}`;
+
+  beforeAll(async () => {
+    const { written } = await runPrerender({
+      prerender: ["/", "/counter"],
+      appDir: FIXTURE_APP,
+      buildDir: TMP_BUILD,
+      manifest: MANIFEST,
+    });
+    expect(written.length).toBe(4); // 2 paths × (index.html + _data.json)
+
+    // Overwrite one artifact with a sentinel so the serving test below can
+    // prove the FILE was served, not a fresh SSR pass.
+    await Bun.write(join(TMP_BUILD, "client", "_prerender", "counter", "index.html"), "<!-- PRERENDERED-SENTINEL -->");
+
+    handle = createServer({
+      port: PORT,
+      appDir: FIXTURE_APP,
+      buildDir: TMP_BUILD,
+      manifest: MANIFEST,
+    });
+  });
+
+  afterAll(async () => {
+    handle.stop();
+    await rm(TMP_BUILD, { recursive: true, force: true });
+  });
+
+  test("writes real SSR output at build time", async () => {
+    const html = await Bun.file(join(TMP_BUILD, "client", "_prerender", "index.html")).text();
+    expect(html).toContain("hello from bractjs"); // loader ran during prerender
+    const data = await Bun.file(join(TMP_BUILD, "client", "_prerender", "_data.json")).json() as { route: { message: string } };
+    expect(data.route.message).toBe("hello from bractjs");
+  });
+
+  test("clean document GETs are served from the prerendered file", async () => {
+    const res = await fetch(`${BASE}/counter`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("PRERENDERED-SENTINEL");
+  });
+
+  test("a query string opts back into dynamic SSR", async () => {
+    const res = await fetch(`${BASE}/counter?fresh=1`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).not.toContain("PRERENDERED-SENTINEL");
+  });
+
+  test("clean /_data is served from the prerendered payload; queried /_data stays dynamic", async () => {
+    const filed = await fetch(`${BASE}/_data?path=/`);
+    expect(filed.headers.get("cache-control")).toContain("must-revalidate");
+    const data = (await filed.json()) as { route: { message: string } };
+    expect(data.route.message).toBe("hello from bractjs");
+
+    // With a query the file is skipped — the loader runs (search echoes back).
+    const dynamic = await fetch(`${BASE}/_data?path=${encodeURIComponent("/?q=1")}`);
+    const dyn = (await dynamic.json()) as { search: Record<string, unknown> };
+    expect(dyn.search).toEqual({ q: "1" });
+  });
+
+  test("non-prerendered paths fall through to dynamic SSR", async () => {
+    const res = await fetch(`${BASE}/search-demo?page=2`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain('"search":{"page":2}');
+  });
+});

package/src/__tests__/programmatic-api.test.ts

@@ -7,7 +7,7 @@
  * Behavioral coverage (HTTP response, HMR) lives in integration.test.ts.
  */
 import { test, expect, describe } from "bun:test";
-import { loadUserConfig, validateUserConfig } from "../config/load.ts";
+import { loadUserConfig, validateUserConfig, defineConfig } from "../config/load.ts";
 import { runBuild } from "../build/bundler.ts";
 import { createDevServer } from "../dev/server.ts";
 import type { BuildConfig } from "../build/bundler.ts";
@@ -60,11 +60,30 @@ describe("validateUserConfig", () => {
     expect(() => validateUserConfig({ sourcemap: "yes" })).toThrow(/"sourcemap" must be/);
   });
 
+  test("rejects a string hmrPort but accepts a number", () => {
+    expect(() => validateUserConfig({ hmrPort: "3001" })).toThrow(/"hmrPort" must be a finite number/);
+    expect(validateUserConfig({ hmrPort: 3005 })).toEqual({ hmrPort: 3005 });
+  });
+
   test("ignores unknown keys and undefined values", () => {
     expect(() => validateUserConfig({ port: undefined, somethingCustom: 1 })).not.toThrow();
   });
 });
 
+// ── defineConfig ──────────────────────────────────────────────────────────
+
+describe("defineConfig", () => {
+  test("is an identity function (returns the same reference)", () => {
+    const cfg = { port: 3000, clientEnv: ["X"] };
+    expect(defineConfig(cfg)).toBe(cfg);
+  });
+
+  test("is re-exported from src/index.ts", async () => {
+    const mod = await import("../index.ts");
+    expect(typeof mod.defineConfig).toBe("function");
+  });
+});
+
 // ── runBuild ──────────────────────────────────────────────────────────────
 
 test("runBuild is exported from build/bundler", () => {

package/src/__tests__/revalidation.test.ts

@@ -0,0 +1,65 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { createServer } from "../server/serve.ts";
+import { registerRevalidator, triggerRevalidation } from "../client/revalidation.ts";
+
+// ── Unit: revalidator seam (router ↔ fetcher bridge) ───────────────────────
+
+describe("revalidation seam", () => {
+  test("triggerRevalidation forwards info to the registered revalidator", async () => {
+    const calls: unknown[] = [];
+    registerRevalidator(async (info) => { calls.push(info); });
+    await triggerRevalidation({ formMethod: "POST", actionStatus: 200 });
+    expect(calls).toEqual([{ formMethod: "POST", actionStatus: 200 }]);
+    registerRevalidator(null);
+  });
+
+  test("resolves quietly when no router is mounted", async () => {
+    registerRevalidator(null);
+    await triggerRevalidation({ formMethod: "DELETE" }); // must not throw
+  });
+});
+
+// ── Integration: the submit → revalidate contract ───────────────────────────
+// ClientRouter.submit POSTs with X-BractJS-Action (JSON action reply), then
+// refetches /_data. This proves the server side of that contract: the mutation
+// changes what the next /_data returns.
+
+const PORT = 3995;
+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("mutation → revalidation contract", () => {
+  test("action mutates, JSON reply carries actionData, /_data reflects the new state", async () => {
+    const before = await (await fetch(`${BASE}/_data?path=/counter`)).json() as { route: { count: number } };
+
+    const post = await fetch(`${BASE}/counter`, {
+      method: "POST",
+      body: new FormData(),
+      headers: { Origin: BASE, "X-BractJS-Action": "1" },
+    });
+    expect(post.status).toBe(200);
+    expect(post.headers.get("content-type")).toContain("json");
+    const actionData = (await post.json()) as { ok: boolean; count: number };
+    expect(actionData.ok).toBe(true);
+    expect(actionData.count).toBe(before.route.count + 1);
+
+    // The revalidation fetch ClientRouter issues after the action:
+    const after = await (await fetch(`${BASE}/_data?path=/counter`)).json() as { route: { count: number } };
+    expect(after.route.count).toBe(before.route.count + 1);
+  });
+});