@cosmicdrift/kumiko-server-runtime 1.0.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "Production server-boot runtime for Kumiko apps: connections, schema-drift-gate, seeds, lifecycle, graceful shutdown. Symmetric to kumiko-dev-server's runDevApp, without dev/scaffold/codegen tooling.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -72,8 +72,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "1.0.0",
-    "@cosmicdrift/kumiko-framework": "1.0.0",
+    "@cosmicdrift/kumiko-bundled-features": "2.0.0",
+    "@cosmicdrift/kumiko-framework": "2.0.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

package/src/__tests__/boot-probe-fixture.ts

@@ -0,0 +1,63 @@
+// Shared fixture for run-prod-app-{dry-run,env-source}.test.ts — both boot
+// runProdApp against a minimal probe feature with process.env cleared so the
+// test fully controls config via envSource. Table/feature name stay
+// parametrized (never collapsed to one shared fixture): a table clash
+// between the two test files' entities would surface as flaky cross-file
+// DB state, not a compile error.
+import { afterEach, beforeEach } from "bun:test";
+import {
+  createBooleanField,
+  createEntity,
+  createTextField,
+  defineFeature,
+  type FeatureDefinition,
+  type FeatureRegistrar,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+
+export function makeProbeFeature(opts: {
+  readonly name: string;
+  readonly table: string;
+  readonly extraSetup?: (r: FeatureRegistrar<string>) => void;
+}): FeatureDefinition {
+  const probeEntity = createEntity({
+    fields: {
+      name: createTextField({ required: true }),
+      active: createBooleanField({ default: true }),
+    },
+    table: opts.table,
+  });
+  return defineFeature(opts.name, (r) => {
+    r.entity("widget", probeEntity);
+    opts.extraSetup?.(r);
+    r.queryHandler({
+      name: "ping",
+      schema: z.object({}),
+      access: { roles: ["anonymous"] },
+      handler: async () => ({ pong: true }),
+    });
+  });
+}
+
+// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws
+// pre-#1441-fix boot bugs); PORT is non-throwing, cleared only so ambient
+// PORT can't mask an "envSource wins" assertion.
+export const CLEARED_BOOT_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
+
+// Registers beforeEach/afterEach for the current describe block — call this
+// at the top of a `describe(...)` body, same as calling beforeEach directly.
+export function withClearedBootEnv(): void {
+  const saved: Record<string, string | undefined> = {};
+  beforeEach(() => {
+    for (const k of CLEARED_BOOT_VARS) {
+      saved[k] = process.env[k];
+      delete process.env[k];
+    }
+  });
+  afterEach(() => {
+    for (const k of CLEARED_BOOT_VARS) {
+      if (saved[k] === undefined) delete process.env[k];
+      else process.env[k] = saved[k];
+    }
+  });
+}

package/src/__tests__/build-prod-bundle.inprocess.test.ts

@@ -0,0 +1,164 @@
+// In-process buildProdBundle — covers Bun.build + HTML render + build-info
+// in the same process (CLI subprocess tests do not contribute to lcov).
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { buildProdBundle } from "../build-prod-bundle";
+
+const REPO_ROOT = resolve(import.meta.dir, "../../../..");
+
+describe("buildProdBundle in-process (Bun.build)", () => {
+  let tmp = "";
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-build-inproc-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  async function writeMinimalClientApp(opts?: { html?: string; client?: string }) {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(
+      join(tmp, "src/client.ts"),
+      opts?.client ??
+        `const root = document.getElementById("root"); if (root) root.textContent = "hi";`,
+    );
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      opts?.html ??
+        `<!doctype html><html><head></head><body><div id="root"></div><script type="module" src="/client.js"></script></body></html>`,
+    );
+    await writeFile(join(tmp, "package.json"), `{"name":"inproc-fixture","private":true}`);
+  }
+
+  test("client.ts → hashed bundle, manifest, build-info, injected script", async () => {
+    await writeMinimalClientApp();
+
+    const result = await buildProdBundle({ cwd: tmp, stylesheet: false });
+
+    expect(result.manifest["client.js"]).toMatch(/^\/assets\/client-[a-z0-9]+\.js$/);
+    expect(result.buildInfo?.id).toMatch(/^[0-9a-f]{12}$/);
+    expect(existsSync(join(tmp, "dist/build-info.json"))).toBe(true);
+
+    const html = await readFile(join(tmp, "dist/index.html"), "utf8");
+    expect(html).toContain(`src="${result.manifest["client.js"]}"`);
+    expect(html).toContain("__KUMIKO_BUILD__");
+
+    const assetPath = join(tmp, "dist", result.manifest["client.js"] ?? "");
+    expect(existsSync(assetPath)).toBe(true);
+    expect(await readFile(assetPath, "utf8")).toContain('"hi"');
+  });
+
+  test("missing index.html → error with template snippet", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client.ts"), `console.log("hi");`);
+    await writeFile(join(tmp, "package.json"), `{"name":"no-html","private":true}`);
+
+    await expect(buildProdBundle({ cwd: tmp, stylesheet: false })).rejects.toThrow(
+      /kein index\.html gefunden/,
+    );
+  });
+
+  test("index.html without /client.js placeholder → error with snippet", async () => {
+    await writeMinimalClientApp({
+      html: `<!doctype html><html><body>no script</body></html>`,
+    });
+
+    await expect(buildProdBundle({ cwd: tmp, stylesheet: false })).rejects.toThrow(
+      /keinen Entry-Tag für \/client\.js/,
+    );
+  });
+
+  test("syntax-broken client → Bun.build rejects", async () => {
+    await writeMinimalClientApp({ client: `const x = {{{` });
+
+    // Bun may throw "Bundle failed" before returning `{ success: false }`.
+    await expect(buildProdBundle({ cwd: tmp, stylesheet: false })).rejects.toThrow(
+      /Bundle failed|Bun\.build failed/,
+    );
+  });
+
+  test("stylesheet override src/styles.css → hashed styles.css in manifest", async () => {
+    // Temp under REPO_ROOT so @tailwindcss/cli + tailwindcss peer resolve
+    // (same constraint as renderer-web-css-relocation.integration.test.ts).
+    const dir = await mkdtemp(join(REPO_ROOT, ".inproc-styles-"));
+    const cwd = join(dir, "app");
+    try {
+      await mkdir(join(cwd, "src"), { recursive: true });
+      await writeFile(
+        join(cwd, "src/client.ts"),
+        `const root = document.getElementById("root"); if (root) root.textContent = "hi";`,
+      );
+      await writeFile(join(cwd, "src/styles.css"), "body { margin: 0; }\n");
+      await mkdir(join(cwd, "public"), { recursive: true });
+      await writeFile(
+        join(cwd, "public/index.html"),
+        `<!doctype html><html><head><link rel="stylesheet" href="/styles.css" /></head><body><div id="root"></div><script type="module" src="/client.js"></script></body></html>`,
+      );
+      await writeFile(join(cwd, "package.json"), `{"name":"inproc-styles","private":true}`);
+
+      const result = await buildProdBundle({ cwd, stylesheet: "src/styles.css" });
+
+      expect(result.manifest["styles.css"]).toMatch(/^\/assets\/styles-[a-z0-9]+\.css$/);
+      const cssPath = join(cwd, "dist", result.manifest["styles.css"] ?? "");
+      expect(existsSync(cssPath)).toBe(true);
+      expect(await readFile(cssPath, "utf8")).toMatch(/margin:\s*0/);
+
+      const html = await readFile(join(cwd, "dist/index.html"), "utf8");
+      expect(html).toContain(`href="${result.manifest["styles.css"]}"`);
+      expect(html).not.toContain('href="/styles.css"');
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing stylesheet override → tailwind rejects", async () => {
+    const dir = await mkdtemp(join(REPO_ROOT, ".inproc-styles-miss-"));
+    const cwd = join(dir, "app");
+    try {
+      await mkdir(join(cwd, "src"), { recursive: true });
+      await writeFile(join(cwd, "src/client.ts"), `console.log("hi");`);
+      await mkdir(join(cwd, "public"), { recursive: true });
+      await writeFile(
+        join(cwd, "public/index.html"),
+        `<!doctype html><html><body><div id="root"></div><script type="module" src="/client.js"></script></body></html>`,
+      );
+      await writeFile(join(cwd, "package.json"), `{"name":"inproc-styles-miss","private":true}`);
+
+      await expect(buildProdBundle({ cwd, stylesheet: "src/missing-theme.css" })).rejects.toThrow(
+        /tailwind|Bundle failed|tailwindcss/i,
+      );
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("multi-entry client-admin + client-public → two hashed bundles", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client-admin.ts"), `console.log("admin");`);
+    await writeFile(join(tmp, "src/client-public.ts"), `console.log("public");`);
+    await mkdir(join(tmp, "public"), { recursive: true });
+    await writeFile(
+      join(tmp, "public/index.html"),
+      `<!doctype html><html><body><script type="module" src="/client-public.js"></script></body></html>`,
+    );
+    await writeFile(
+      join(tmp, "admin.html"),
+      `<!doctype html><html><body><script type="module" src="/client-admin.js"></script></body></html>`,
+    );
+    await writeFile(join(tmp, "package.json"), `{"name":"multi-inproc","private":true}`);
+
+    const result = await buildProdBundle({ cwd: tmp, stylesheet: false });
+
+    expect(result.manifest["client-admin.js"]).toMatch(/^\/assets\/client-admin-/);
+    expect(result.manifest["client-public.js"]).toMatch(/^\/assets\/client-public-/);
+    expect(existsSync(join(tmp, "dist/admin.html"))).toBe(true);
+    expect(existsSync(join(tmp, "dist/index.html"))).toBe(true);
+  });
+});

package/src/__tests__/compose-features.test.ts

@@ -76,6 +76,39 @@ describe("composeFeatures", () => {
     expect(handlerNames).toContain("signup-confirm");
   });
 
+  // Regression: signup-request no-ops silently (always-200 anti-enumeration
+  // contract) unless "auth-self-registration" is mounted. composeFeatures
+  // must bundle it alongside authOptions.signup, not leave apps using the
+  // includeBundled convenience path to mount it by hand.
+  test("authOptions.signup → auth-self-registration mounted, default ON", () => {
+    const features = composeFeatures([noopFeature], {
+      includeBundled: true,
+      authOptions: { signup: { appUrl: "https://app/signup/complete" } },
+    });
+    const toggle = features.find((f) => f.name === "auth-self-registration");
+    expect(toggle).toBeDefined();
+    // The security-relevant part isn't that the feature is mounted, it's
+    // that self-signup defaults ON — a flip to `default: false` upstream
+    // would silently no-op signup (always-200 anti-enumeration masks it)
+    // while this assertion alone (toBeDefined) stayed green.
+    expect(toggle?.toggleableDefault).toBe(true);
+  });
+
+  test("no authOptions.signup → auth-self-registration NOT mounted", () => {
+    const features = composeFeatures([noopFeature], { includeBundled: true });
+    expect(features.map((f) => f.name)).not.toContain("auth-self-registration");
+  });
+
+  test("authOptions.signup + app also mounts its own auth-self-registration stub → deduped to exactly one", () => {
+    const pickerSelfRegDupe = defineFeature("auth-self-registration", () => {});
+    const features = composeFeatures([noopFeature, pickerSelfRegDupe], {
+      includeBundled: true,
+      authOptions: { signup: { appUrl: "https://app/signup/complete" } },
+    });
+    const names = features.map((f) => f.name).filter((n) => n === "auth-self-registration");
+    expect(names).toEqual(["auth-self-registration"]);
+  });
+
   test("OHNE authOptions → KEINE reset/verify-handlers (anti-default-deploy-bug)", () => {
     // Genau der Bug der vom Review-Agent gefangen wurde: composeFeatures
     // ohne authOptions registriert die handler nicht. Wenn jemand das

package/src/__tests__/run-prod-app-dry-run.test.ts

@@ -0,0 +1,135 @@
+// Dry-run + bootErrorReporter paths — no DB/Redis. envSource avoids process.exit(0).
+
+import { describe, expect, test } from "bun:test";
+import { composeEnvSchema, KumikoBootError } from "@cosmicdrift/kumiko-framework/env";
+import { z } from "zod";
+import { runProdApp } from "../run-prod-app";
+import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
+
+const probeFeature = makeProbeFeature({
+  name: "dry-run-probe",
+  table: "dry_run_probe",
+  extraSetup: (r) => {
+    r.envSchema(z.object({ DRY_RUN_PROBE: z.string().optional().describe("probe var") }));
+  },
+});
+
+describe("runProdApp dry-run / bootErrorReporter", () => {
+  withClearedBootEnv();
+
+  test("KUMIKO_DRY_RUN_ENV=human + envSource → render + dry-run handle (no exit)", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    const envSchema = composeEnvSchema({ features: [probeFeature] });
+    let handle: Awaited<ReturnType<typeof runProdApp>>;
+    try {
+      handle = await runProdApp({
+        features: [probeFeature],
+        envSchema,
+        autoListen: false,
+        migrations: false,
+        envSource: { KUMIKO_DRY_RUN_ENV: "human" },
+      });
+    } finally {
+      console.log = originalLog;
+    }
+
+    expect(logs.some((l) => l.includes("DRY_RUN_PROBE"))).toBe(true);
+    const res = await handle!.fetch(new Request("http://test/"));
+    expect(res.status).toBe(503);
+    expect(await res.text()).toBe("dry-run");
+    await handle!.stop();
+  });
+
+  test("KUMIKO_DRY_RUN_ENV=json → structured dry-run output", async () => {
+    const logs: string[] = [];
+    const originalLog = console.log;
+    console.log = (...args: unknown[]) => {
+      logs.push(args.map(String).join(" "));
+    };
+    const envSchema = composeEnvSchema({ features: [probeFeature] });
+    try {
+      const handle = await runProdApp({
+        features: [probeFeature],
+        envSchema,
+        autoListen: false,
+        migrations: false,
+        envSource: { KUMIKO_DRY_RUN_ENV: "json" },
+      });
+      await handle.stop();
+    } finally {
+      console.log = originalLog;
+    }
+    const jsonLine = logs.find((l) => l.trimStart().startsWith("{"));
+    if (!jsonLine) throw new Error(`No JSON line in logs: ${JSON.stringify(logs)}`);
+    const parsed = JSON.parse(jsonLine) as {
+      optional: Array<{ name: string; feature: string }>;
+    };
+    expect(parsed.optional).toContainEqual(
+      expect.objectContaining({ name: "DRY_RUN_PROBE", feature: "dry-run-probe" }),
+    );
+  });
+
+  test("unrecognized KUMIKO_DRY_RUN_ENV warns then hits envSchema parse", async () => {
+    const warnings: string[] = [];
+    const originalWarn = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    const envSchema = composeEnvSchema({
+      features: [],
+      extend: z.object({ MUST_HAVE: z.string().describe("required for test") }),
+    });
+    try {
+      await expect(
+        runProdApp({
+          features: [probeFeature],
+          envSchema,
+          autoListen: false,
+          migrations: false,
+          envSource: { KUMIKO_DRY_RUN_ENV: "not-a-real-mode" },
+          bootErrorReporter: (err) => {
+            throw err;
+          },
+        }),
+      ).rejects.toBeInstanceOf(KumikoBootError);
+    } finally {
+      console.warn = originalWarn;
+    }
+    expect(
+      warnings.some(
+        (w) => w.includes('KUMIKO_DRY_RUN_ENV="not-a-real-mode"') && w.includes("unrecognized"),
+      ),
+    ).toBe(true);
+  });
+
+  test("bootErrorReporter receives KumikoBootError instead of process.exit", async () => {
+    const envSchema = composeEnvSchema({
+      features: [],
+      extend: z.object({ MUST_HAVE: z.string().describe("required for test") }),
+    });
+    let reported: KumikoBootError | undefined;
+    await expect(
+      runProdApp({
+        features: [probeFeature],
+        envSchema,
+        autoListen: false,
+        migrations: false,
+        envSource: {
+          // no MUST_HAVE → parseEnv throws KumikoBootError
+          DATABASE_URL: "postgres://x",
+          REDIS_URL: "redis://x",
+        },
+        bootErrorReporter: (err) => {
+          reported = err;
+          throw err;
+        },
+      }),
+    ).rejects.toBeInstanceOf(KumikoBootError);
+    expect(reported).toBeInstanceOf(KumikoBootError);
+    expect(reported!.errors.some((e) => e.name === "MUST_HAVE")).toBe(true);
+  });
+});

package/src/__tests__/run-prod-app-env-source.test.ts

@@ -6,40 +6,15 @@
 // required-var test would throw "required env var DATABASE_URL is missing" and
 // the PORT test would bind the default instead of the injected port.
 
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import {
-  createBooleanField,
-  createEntity,
-  createTextField,
-  defineFeature,
-} from "@cosmicdrift/kumiko-framework/engine";
-import { z } from "zod";
+import { describe, expect, test } from "bun:test";
 import { runProdApp } from "../run-prod-app";
+import { makeProbeFeature, withClearedBootEnv } from "./boot-probe-fixture";
 
-const probeEntity = createEntity({
-  fields: {
-    name: createTextField({ required: true }),
-    active: createBooleanField({ default: true }),
-  },
+const probeFeature = makeProbeFeature({
+  name: "env-source-probe",
   table: "env_source_probe",
 });
 
-const probeFeature = defineFeature("env-source-probe", (r) => {
-  r.entity("widget", probeEntity);
-  r.queryHandler({
-    name: "ping",
-    schema: z.object({}),
-    access: { roles: ["anonymous"] },
-    handler: async () => ({ pong: true }),
-  });
-});
-
-// Cleared from process.env so the test fully controls config via envSource.
-// DATABASE_URL/REDIS_URL/JWT_SECRET are required (their read throws pre-fix);
-// PORT is non-throwing, cleared only so ambient PORT can't mask the second
-// test's "PORT comes from envSource" assertion.
-const CLEARED_VARS = ["DATABASE_URL", "REDIS_URL", "JWT_SECRET", "PORT"] as const;
-
 const DUMMY_ENV = {
   KUMIKO_DRY_RUN_ENV: "boot",
   DATABASE_URL: "postgres://smoke:smoke@127.0.0.1:1/smoke",
@@ -48,21 +23,7 @@ const DUMMY_ENV = {
 } as const;
 
 describe("runProdApp boot-mode env-source", () => {
-  const saved: Record<string, string | undefined> = {};
-
-  beforeEach(() => {
-    for (const k of CLEARED_VARS) {
-      saved[k] = process.env[k];
-      delete process.env[k];
-    }
-  });
-
-  afterEach(() => {
-    for (const k of CLEARED_VARS) {
-      if (saved[k] === undefined) delete process.env[k];
-      else process.env[k] = saved[k];
-    }
-  });
+  withClearedBootEnv();
 
   test("boots from injected envSource even when process.env lacks the required vars", async () => {
     const logs: string[] = [];

package/src/__tests__/run-prod-app-static-files.test.ts

@@ -0,0 +1,171 @@
+// Unit coverage for mimeTypeFor + hostDispatch edge in buildStaticFallback.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  buildStaticFallback,
+  mimeTypeFor,
+  readStaticFile,
+  serveDiskFile,
+} from "../run-prod-app-static-files";
+
+describe("mimeTypeFor", () => {
+  const cases: ReadonlyArray<readonly [string, string]> = [
+    ["x.html", "text/html; charset=utf-8"],
+    ["x.js", "text/javascript; charset=utf-8"],
+    ["x.mjs", "text/javascript; charset=utf-8"],
+    ["x.css", "text/css; charset=utf-8"],
+    ["x.json", "application/json; charset=utf-8"],
+    ["x.svg", "image/svg+xml"],
+    ["x.png", "image/png"],
+    ["x.jpg", "image/jpeg"],
+    ["x.jpeg", "image/jpeg"],
+    ["x.ico", "image/x-icon"],
+    ["x.txt", "text/plain; charset=utf-8"],
+    ["x.xml", "application/xml; charset=utf-8"],
+    ["x.webmanifest", "application/manifest+json"],
+    ["x.bin", "application/octet-stream"],
+    ["noext", "application/octet-stream"],
+  ];
+
+  for (const [path, mime] of cases) {
+    test(`${path} → ${mime}`, () => {
+      expect(mimeTypeFor(path)).toBe(mime);
+    });
+  }
+});
+
+describe("readStaticFile / serveDiskFile", () => {
+  let tmp = "";
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-static-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("readStaticFile returns bytes+mime; ENOENT → undefined", async () => {
+    const path = join(tmp, "a.css");
+    await writeFile(path, "body{}");
+    const file = await readStaticFile(path);
+    expect(file?.mime).toBe("text/css; charset=utf-8");
+    expect(new TextDecoder().decode(file!.bytes)).toBe("body{}");
+    expect(await readStaticFile(join(tmp, "missing.css"))).toBeUndefined();
+  });
+
+  test("readStaticFile on a directory → undefined (EISDIR), not a throw", async () => {
+    const dirPath = join(tmp, "sub");
+    await mkdir(dirPath);
+    expect(await readStaticFile(dirPath)).toBeUndefined();
+  });
+
+  test("readStaticFile through a file used as a directory segment → undefined (ENOTDIR), not a throw (#1504)", async () => {
+    const path = join(tmp, "index.html");
+    await writeFile(path, "<html/>");
+    // GET /index.html/x — "index.html" is a file, so treating it as a
+    // directory segment must fall through to the SPA fallback, not 500.
+    expect(await readStaticFile(join(path, "x"))).toBeUndefined();
+  });
+
+  test("serveDiskFile sets content-type from mime", async () => {
+    const path = join(tmp, "a.svg");
+    await writeFile(path, "<svg/>");
+    const file = await readStaticFile(path);
+    const res = serveDiskFile(new Request("http://t/a.svg"), "/a.svg", file!);
+    expect(res.headers.get("content-type")).toBe("image/svg+xml");
+    expect(await res.text()).toBe("<svg/>");
+  });
+});
+
+describe("buildStaticFallback hostDispatch", () => {
+  let tmp = "";
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), "kumiko-fallback-"));
+  });
+
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true });
+  });
+
+  test("hostDispatch html pointing at missing file → 500", async () => {
+    const handler = buildStaticFallback(
+      () => new Response("api-404", { status: 404 }),
+      tmp,
+      "{}",
+      () => ({ kind: "html", file: "gone.html" }),
+    );
+    const res = await handler(new Request("http://t/"));
+    expect(res.status).toBe(500);
+    expect(await res.text()).toContain("hostDispatch: file not found: gone.html");
+  });
+
+  test("hostDispatch not-found → 404; redirect → 302", async () => {
+    const notFound = buildStaticFallback(
+      () => new Response("x", { status: 404 }),
+      tmp,
+      "{}",
+      () => ({ kind: "not-found" }),
+    );
+    expect((await notFound(new Request("http://t/"))).status).toBe(404);
+
+    const redirect = buildStaticFallback(
+      () => new Response("x", { status: 404 }),
+      tmp,
+      "{}",
+      () => ({ kind: "redirect", to: "https://example.com/", status: 301 }),
+    );
+    const res = await redirect(new Request("http://t/"));
+    expect(res.status).toBe(301);
+    expect(res.headers.get("location")).toBe("https://example.com/");
+  });
+
+  test("/api/* always hits apiHandler", async () => {
+    const handler = buildStaticFallback(() => new Response("from-api", { status: 200 }), tmp, "{}");
+    const res = await handler(new Request("http://t/api/query", { method: "POST" }));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toBe("from-api");
+  });
+
+  test("serves disk asset under staticDir", async () => {
+    await writeFile(join(tmp, "logo.png"), "PNGDATA");
+    const handler = buildStaticFallback(() => new Response("404", { status: 404 }), tmp, "{}");
+    const res = await handler(new Request("http://t/logo.png"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("image/png");
+    expect(await res.text()).toBe("PNGDATA");
+  });
+
+  test("a request for a directory copied verbatim from public/ falls back to index.html instead of 500ing", async () => {
+    await mkdir(join(tmp, "sub"));
+    await writeFile(join(tmp, "index.html"), "<!doctype html><html><body>spa-shell</body></html>");
+    const handler = buildStaticFallback(() => new Response("404", { status: 404 }), tmp, "{}");
+    const res = await handler(new Request("http://t/sub"));
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("spa-shell");
+  });
+
+  test("hostDispatch html with CSP + Vary: Host", async () => {
+    await writeFile(join(tmp, "tenant.html"), "<!doctype html><html><body>ok</body></html>");
+    const handler = buildStaticFallback(
+      () => new Response("404", { status: 404 }),
+      tmp,
+      '{"screens":[]}',
+      () => ({
+        kind: "html",
+        file: "tenant.html",
+        injectSchema: false,
+        csp: "default-src 'self'",
+      }),
+    );
+    const res = await handler(new Request("http://t/", { headers: { host: "a.example" } }));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("vary")).toBe("Host");
+    expect(res.headers.get("content-security-policy")).toBe("default-src 'self'");
+    expect(await res.text()).toContain("ok");
+  });
+});