@bractjs/bractjs 0.1.26 → 0.1.28

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__/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);
+  });
+});

package/src/__tests__/route-lint.test.ts

@@ -0,0 +1,74 @@
+import { test, expect, describe } from "bun:test";
+import { lintRouteModuleSource } from "../build/route-lint.ts";
+
+describe("lintRouteModuleSource — empty routes", () => {
+  test("warns when a route has no meaningful export", () => {
+    const w = lintRouteModuleSource(`export const meta = () => [];\n`, "routes/empty.tsx");
+    expect(w.some((m) => /renders an empty page/.test(m))).toBe(true);
+  });
+
+  test("loader-only is fine (data route)", () => {
+    const w = lintRouteModuleSource(`export function loader() { return {}; }\n`, "routes/data.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("beforeLoad-only is fine (redirect/guard route)", () => {
+    const w = lintRouteModuleSource(`export function beforeLoad() {}\n`, "routes/guard.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("named default is fine", () => {
+    const w = lintRouteModuleSource(`export default function Page() { return null; }\n`, "routes/p.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("anonymous arrow default is recognized as a component", () => {
+    const w = lintRouteModuleSource(`export default () => null;\n`, "routes/anon.tsx");
+    expect(w).toEqual([]);
+  });
+
+  test("anonymous function default is recognized", () => {
+    const w = lintRouteModuleSource(`export default function () { return null; }\n`, "routes/anon2.tsx");
+    expect(w).toEqual([]);
+  });
+});
+
+describe("lintRouteModuleSource — miscased exports", () => {
+  test('"Loader" is flagged as a near-miss of "loader"', () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\nexport function Loader() { return {}; }\n`,
+      "routes/x.tsx",
+    );
+    expect(w.some((m) => /"Loader" looks like "loader"/.test(m))).toBe(true);
+  });
+
+  test('"fallback" → "Fallback", "beforeload" → "beforeLoad"', () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\n` +
+        `export const fallback = () => null;\n` +
+        `export function beforeload() {}\n`,
+      "routes/y.tsx",
+    );
+    expect(w.some((m) => /"fallback" looks like "Fallback"/.test(m))).toBe(true);
+    expect(w.some((m) => /"beforeload" looks like "beforeLoad"/.test(m))).toBe(true);
+  });
+
+  test("exact canonical names produce no near-miss warnings", () => {
+    const src =
+      `export default () => null;\n` +
+      `export function loader() { return {}; }\n` +
+      `export function action() { return {}; }\n` +
+      `export const searchSchema = {};\n` +
+      `export function Fallback() { return null; }\n` +
+      `export const ssr = false;\n`;
+    expect(lintRouteModuleSource(src, "routes/z.tsx")).toEqual([]);
+  });
+
+  test("unrelated exports are not flagged", () => {
+    const w = lintRouteModuleSource(
+      `export default () => null;\nexport const helper = 1;\nexport type Foo = string;\n`,
+      "routes/h.tsx",
+    );
+    expect(w).toEqual([]);
+  });
+});

package/src/__tests__/route-table.test.ts

@@ -0,0 +1,33 @@
+import { test, expect, describe } from "bun:test";
+import { formatRouteTable } from "../dev/route-table.ts";
+
+describe("formatRouteTable", () => {
+  test("empty → a clear no-routes line", () => {
+    expect(formatRouteTable([])).toBe("[bractjs] no routes found under routes/");
+  });
+
+  test("lists routes sorted by pattern with loader/action markers", () => {
+    const out = formatRouteTable([
+      { pattern: "/blog/:id", file: "routes/blog/[id].tsx", hasLoader: true, hasAction: true },
+      { pattern: "/", file: "routes/_index.tsx", hasLoader: true, hasAction: false },
+    ]);
+    // Header reports the count.
+    expect(out).toContain("[bractjs] 2 routes:");
+    // Sorted: "/" before "/blog/:id".
+    expect(out.indexOf("routes/_index.tsx")).toBeLessThan(out.indexOf("routes/blog/[id].tsx"));
+    // Markers present.
+    expect(out).toContain("loader");
+    expect(out).toContain("action");
+    // The index route shows loader but not action.
+    const indexLine = out.split("\n").find((l) => l.includes("_index"))!;
+    expect(indexLine).toContain("loader");
+    expect(indexLine).not.toContain("action");
+  });
+
+  test("singular wording for one route", () => {
+    const out = formatRouteTable([
+      { pattern: "/", file: "routes/_index.tsx", hasLoader: false, hasAction: false },
+    ]);
+    expect(out).toContain("1 route:");
+  });
+});

package/src/__tests__/safe-validate.test.ts

@@ -0,0 +1,96 @@
+import { test, expect, describe } from "bun:test";
+import {
+  safeValidate,
+  isValidationResponse,
+  readValidationError,
+  type Schema,
+} from "../server/validate.ts";
+
+// A Zod/Valibot-style safeParse schema: requires non-empty `title`.
+const TitleSchema: Schema<{ title: string }> = {
+  safeParse(input: unknown) {
+    const raw = (input as { title?: unknown })?.title;
+    const title = typeof raw === "string" ? raw.trim() : "";
+    if (!title) {
+      return { success: false, error: { issues: [{ path: ["title"], message: "Title is required." }] } };
+    }
+    return { success: true, data: { title } };
+  },
+};
+
+// A `.parse()`-only schema that throws.
+const ThrowingSchema: Schema<{ n: number }> = {
+  parse(input: unknown) {
+    const n = Number((input as { n?: unknown })?.n);
+    if (!Number.isFinite(n)) throw new Error("n must be a number");
+    return { n };
+  },
+};
+
+describe("safeValidate", () => {
+  test("ok path returns parsed data", async () => {
+    const r = await safeValidate(TitleSchema, { title: "  hi  " });
+    expect(r).toEqual({ ok: true, data: { title: "hi" } });
+  });
+
+  test("safeParse failure → fieldErrors + firstError", async () => {
+    const r = await safeValidate(TitleSchema, { title: "" });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.fieldErrors).toEqual({ title: ["Title is required."] });
+      expect(r.firstError).toBe("Title is required.");
+    }
+  });
+
+  test("parse-throw failure → _ field + message", async () => {
+    const r = await safeValidate(ThrowingSchema, { n: "abc" });
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.fieldErrors._).toEqual(["n must be a number"]);
+      expect(r.firstError).toBe("n must be a number");
+    }
+  });
+
+  test("works with FormData input", async () => {
+    const fd = new FormData();
+    fd.set("title", "from form");
+    const r = await safeValidate(TitleSchema, fd);
+    expect(r).toEqual({ ok: true, data: { title: "from form" } });
+  });
+});
+
+describe("isValidationResponse", () => {
+  test("true for the Response thrown by validation", async () => {
+    // safeValidate swallows it, so trigger the throw via the underlying runSchema path:
+    let thrown: unknown;
+    try {
+      const { validate } = await import("../server/validate.ts");
+      await validate(TitleSchema, { title: "" });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(isValidationResponse(thrown)).toBe(true);
+  });
+
+  test("false for a plain 400 Response without the validation statusText", () => {
+    expect(isValidationResponse(new Response(null, { status: 400 }))).toBe(false);
+    expect(isValidationResponse(new Error("nope"))).toBe(false);
+    expect(isValidationResponse(null)).toBe(false);
+  });
+});
+
+describe("readValidationError", () => {
+  test("parses { errors } body", async () => {
+    const res = Response.json({ errors: { email: ["Invalid"] } }, { status: 400 });
+    const { fieldErrors, firstError } = await readValidationError(res);
+    expect(fieldErrors).toEqual({ email: ["Invalid"] });
+    expect(firstError).toBe("Invalid");
+  });
+
+  test("falls back gracefully on non-JSON body", async () => {
+    const res = new Response("not json", { status: 400 });
+    const { fieldErrors, firstError } = await readValidationError(res);
+    expect(fieldErrors).toEqual({});
+    expect(firstError).toBe("Please check your input.");
+  });
+});

package/src/__tests__/scroll-restoration.test.ts

@@ -0,0 +1,66 @@
+import { test, expect, describe } from "bun:test";
+import {
+  savePosition,
+  serializePositions,
+  deserializePositions,
+  MAX_SCROLL_ENTRIES,
+} from "../client/scroll-restoration.ts";
+
+describe("savePosition", () => {
+  test("stores and overwrites a key", () => {
+    const map = new Map<string, number>();
+    savePosition(map, "a", 100);
+    savePosition(map, "a", 250);
+    expect(map.get("a")).toBe(250);
+    expect(map.size).toBe(1);
+  });
+
+  test("evicts the oldest entries past the cap", () => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < 5; i++) savePosition(map, `k${i}`, i, 3);
+    expect(map.size).toBe(3);
+    expect(map.has("k0")).toBe(false);
+    expect(map.has("k1")).toBe(false);
+    expect(map.get("k4")).toBe(4);
+  });
+
+  test("re-saving refreshes LRU order", () => {
+    const map = new Map<string, number>();
+    savePosition(map, "a", 1, 2);
+    savePosition(map, "b", 2, 2);
+    savePosition(map, "a", 10, 2); // refresh "a" → "b" is now oldest
+    savePosition(map, "c", 3, 2);
+    expect(map.has("b")).toBe(false);
+    expect(map.get("a")).toBe(10);
+    expect(map.get("c")).toBe(3);
+  });
+
+  test("default cap is applied", () => {
+    const map = new Map<string, number>();
+    for (let i = 0; i < MAX_SCROLL_ENTRIES + 10; i++) savePosition(map, `k${i}`, i);
+    expect(map.size).toBe(MAX_SCROLL_ENTRIES);
+  });
+});
+
+describe("serialize/deserialize", () => {
+  test("roundtrips entries", () => {
+    const map = new Map<string, number>([["a", 0], ["b", 1234.5]]);
+    const restored = deserializePositions(serializePositions(map));
+    expect(restored.get("a")).toBe(0);
+    expect(restored.get("b")).toBe(1234.5);
+    expect(restored.size).toBe(2);
+  });
+
+  test("null/malformed/foreign payloads yield an empty map", () => {
+    expect(deserializePositions(null).size).toBe(0);
+    expect(deserializePositions("not json{").size).toBe(0);
+    expect(deserializePositions('"a string"').size).toBe(0);
+    expect(deserializePositions("[1,2,3]").size).toBe(0);
+  });
+
+  test("non-numeric values are dropped", () => {
+    const restored = deserializePositions('{"a": 10, "b": "nope", "c": null, "d": 1e999}');
+    expect(restored.get("a")).toBe(10);
+    expect(restored.size).toBe(1); // "d" is Infinity after JSON.parse → dropped
+  });
+});

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

@@ -0,0 +1,42 @@
+import { test, expect, describe } from "bun:test";
+import { serializeSearch, withSearch } from "../client/search-serializer.ts";
+
+describe("serializeSearch", () => {
+  test("primitives stringify", () => {
+    expect(serializeSearch({ page: 2, q: "hi", on: true })).toBe("?page=2&q=hi&on=true");
+  });
+
+  test("undefined/null drop the key", () => {
+    expect(serializeSearch({ a: 1, b: undefined, c: null })).toBe("?a=1");
+  });
+
+  test("arrays become repeated keys (inverse of searchParamsToObject)", () => {
+    expect(serializeSearch({ tag: ["a", "b"] })).toBe("?tag=a&tag=b");
+  });
+
+  test("nested objects JSON-stringify", () => {
+    expect(serializeSearch({ f: { x: 1 } })).toBe("?f=" + encodeURIComponent('{"x":1}'));
+  });
+
+  test("empty object → empty string", () => {
+    expect(serializeSearch({})).toBe("");
+  });
+
+  test("values are URL-encoded", () => {
+    expect(serializeSearch({ q: "a b&c" })).toBe("?q=a+b%26c");
+  });
+});
+
+describe("withSearch", () => {
+  test("appends search to a bare path", () => {
+    expect(withSearch("/posts", { page: 2 })).toBe("/posts?page=2");
+  });
+
+  test("replaces an existing query, preserves the hash", () => {
+    expect(withSearch("/posts?old=1#top", { page: 2 })).toBe("/posts?page=2#top");
+  });
+
+  test("no search → path untouched", () => {
+    expect(withSearch("/posts?old=1")).toBe("/posts?old=1");
+  });
+});