@cosmicdrift/kumiko-server-runtime 0.322.0 → 0.323.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-server-runtime",
-  "version": "0.322.0",
+  "version": "0.323.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>",
@@ -76,9 +76,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-bundled-features": "0.322.0",
-    "@cosmicdrift/kumiko-framework": "0.322.0",
-    "@cosmicdrift/kumiko-headless": "0.322.0",
+    "@cosmicdrift/kumiko-bundled-features": "0.323.0",
+    "@cosmicdrift/kumiko-framework": "0.323.0",
+    "@cosmicdrift/kumiko-headless": "0.323.0",
     "temporal-polyfill": "^0.3.2"
   },
   "publishConfig": {

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

@@ -2,7 +2,7 @@
 // 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 { existsSync, readdirSync } from "node:fs";
 import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -139,7 +139,7 @@ describe("buildProdBundle in-process (Bun.build)", () => {
     }
   });
 
-  test("multi-entry client-admin + client-public → two hashed bundles", async () => {
+  test("multi-entry client-admin + client-public via kumiko.clientEntries → 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");`);
@@ -154,11 +154,40 @@ describe("buildProdBundle in-process (Bun.build)", () => {
     );
     await writeFile(join(tmp, "package.json"), `{"name":"multi-inproc","private":true}`);
 
-    const result = await buildProdBundle({ cwd: tmp, stylesheet: false });
+    const result = await buildProdBundle({
+      cwd: tmp,
+      stylesheet: false,
+      clientEntries: [
+        { name: "admin", sourceFile: "./src/client-admin.ts" },
+        { name: "public", sourceFile: "./src/client-public.ts" },
+      ],
+    });
 
     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);
   });
+
+  test("undeclared helper next to declared entries produces no bundle for it", async () => {
+    await mkdir(join(tmp, "src"), { recursive: true });
+    await writeFile(join(tmp, "src/client-public.ts"), `console.log("public");`);
+    await writeFile(join(tmp, "src/client-helper.ts"), `export const helper = "unused";`);
+    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, "package.json"), `{"name":"undeclared-helper","private":true}`);
+
+    const result = await buildProdBundle({
+      cwd: tmp,
+      stylesheet: false,
+      clientEntries: [{ name: "public", sourceFile: "./src/client-public.ts" }],
+    });
+
+    expect(Object.keys(result.manifest)).toEqual(["client-public.js"]);
+    const assetFiles = readdirSync(join(tmp, "dist/assets"));
+    expect(assetFiles.some((f) => f.startsWith("client-helper-"))).toBe(false);
+  });
 });

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

@@ -14,15 +14,17 @@ import { join } from "node:path";
 import {
   buildMissingTemplateError,
   type ClientEntry,
+  type ClientEntryDeclaration,
   computeBuildId,
-  discoverClientEntries,
   discoverHtmlTemplate,
   formatBuildResult,
   injectAssetTags,
+  readClientEntriesConfig,
+  resolveClientEntries,
 } from "../build-prod-bundle";
 
-// Synthetic single-entry helper. Realer Build erzeugt das via
-// discoverClientEntries; hier reicht die Form für injectAssetTags-Tests.
+// Synthetic single-entry: injectAssetTags only needs the shape, not a
+// resolveClientEntries round-trip.
 function clientEntry(): ClientEntry {
   return {
     name: "client",
@@ -41,7 +43,11 @@ function namedEntry(name: string): ClientEntry {
   };
 }
 
-describe("build-prod-bundle/discovery", () => {
+async function writeJson(path: string, value: unknown): Promise<void> {
+  await writeFile(path, JSON.stringify(value));
+}
+
+describe("build-prod-bundle/discovery (convention mode)", () => {
   let workDir = "";
 
   beforeEach(async () => {
@@ -52,11 +58,11 @@ describe("build-prod-bundle/discovery", () => {
     await rm(workDir, { recursive: true, force: true });
   });
 
-  test("discoverClientEntries findet single-mode src/client.tsx", async () => {
+  test("resolveClientEntries findet single-mode src/client.tsx wenn nichts deklariert ist", async () => {
     await mkdir(join(workDir, "src"), { recursive: true });
     await writeFile(join(workDir, "src/client.tsx"), "// single");
 
-    const entries = discoverClientEntries(workDir);
+    const entries = resolveClientEntries(workDir, {});
 
     expect(entries).toHaveLength(1);
     expect(entries[0]?.name).toBe("client");
@@ -64,41 +70,46 @@ describe("build-prod-bundle/discovery", () => {
     expect(entries[0]?.htmlPath).toBe("index.html");
   });
 
-  test("discoverClientEntries findet multi-mode client-public + client-admin", async () => {
-    await mkdir(join(workDir, "src"), { recursive: true });
-    await writeFile(join(workDir, "src/client-public.tsx"), "// public");
-    await writeFile(join(workDir, "src/client-admin.tsx"), "// admin");
-
-    const entries = discoverClientEntries(workDir);
+  test("resolveClientEntries gibt leeres Array zurück wenn nichts da und nichts deklariert ist", () => {
+    expect(resolveClientEntries(workDir, {})).toEqual([]);
+  });
 
-    // Sortiert nach name.
-    expect(entries.map((e) => e.name)).toEqual(["admin", "public"]);
+  // #2305 regression: a plain module imported by the real entry, named
+  // like a legacy client-<suffix>.tsx file, must not turn into an error or
+  // a second entry once src/client.tsx exists (single mode wins outright).
+  test("src/client.tsx neben src/client-utils.tsx → genau ein Entry, kein Fehler", async () => {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    await writeFile(join(workDir, "src/client.tsx"), "// real entry");
+    await writeFile(join(workDir, "src/client-utils.tsx"), "export const utils = [];");
 
-    const admin = entries.find((e) => e.name === "admin");
-    expect(admin?.manifestKey).toBe("client-admin.js");
-    expect(admin?.htmlPath).toBe("admin.html");
+    const entries = resolveClientEntries(workDir, {});
 
-    const pub = entries.find((e) => e.name === "public");
-    expect(pub?.manifestKey).toBe("client-public.js");
-    // "public" mappt auf das Default-Template (index.html), nicht
-    // public.html — das ist Convention damit das default-served-Template
-    // den vom-User-erwarteten Namen behält.
-    expect(pub?.htmlPath).toBe("index.html");
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.name).toBe("client");
   });
 
-  test("discoverClientEntries multi-mode dominiert über single-mode wenn beide da", async () => {
+  test("legacy src/client-<suffix>.tsx ohne Deklaration → Migrations-Fehler mit package.json-Snippet", async () => {
     await mkdir(join(workDir, "src"), { recursive: true });
-    await writeFile(join(workDir, "src/client.tsx"), "// single");
     await writeFile(join(workDir, "src/client-admin.tsx"), "// admin");
+    await writeFile(join(workDir, "src/client-public.tsx"), "// public");
 
-    const entries = discoverClientEntries(workDir);
-
-    // Multi-mode aktiv → "client" wird ignoriert.
-    expect(entries.map((e) => e.name)).toEqual(["admin"]);
+    expect(() => resolveClientEntries(workDir, {})).toThrow(/client-admin\.tsx/);
+    expect(() => resolveClientEntries(workDir, {})).toThrow(/client-public\.tsx/);
+    expect(() => resolveClientEntries(workDir, {})).toThrow(/kumiko\.clientEntries/);
+    expect(() => resolveClientEntries(workDir, {})).toThrow(
+      /"name":\s*"admin",\s*"sourceFile":\s*"\.\/src\/client-admin\.tsx"/,
+    );
   });
 
-  test("discoverClientEntries gibt leeres Array zurück wenn nichts da", () => {
-    expect(discoverClientEntries(workDir)).toEqual([]);
+  test("legacy src/client-<suffix>.ts (kein x) → Migrations-Snippet nennt die exakte .ts-Extension", async () => {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    await writeFile(join(workDir, "src/client-admin.ts"), "// admin");
+
+    expect(() => resolveClientEntries(workDir, {})).toThrow(/src\/client-admin\.ts\b/);
+    expect(() => resolveClientEntries(workDir, {})).toThrow(
+      /"sourceFile":\s*"\.\/src\/client-admin\.ts"/,
+    );
+    expect(() => resolveClientEntries(workDir, {})).not.toThrow(/client-admin\.tsx/);
   });
 
   test("discoverHtmlTemplate findet index.html im cwd", async () => {
@@ -128,6 +139,350 @@ describe("build-prod-bundle/discovery", () => {
   });
 });
 
+describe("build-prod-bundle/resolveClientEntries (declared)", () => {
+  let workDir = "";
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(join(tmpdir(), "kumiko-build-declared-"));
+  });
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true });
+  });
+
+  async function writeSourceFiles(names: readonly string[]): Promise<void> {
+    await mkdir(join(workDir, "src"), { recursive: true });
+    for (const name of names) {
+      await writeFile(join(workDir, `src/${name}`), `// ${name}`);
+    }
+  }
+
+  test("clientEntry → single entry named 'client'", async () => {
+    await writeSourceFiles(["main.tsx"]);
+
+    const entries = resolveClientEntries(workDir, { clientEntry: "./src/main.tsx" });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.name).toBe("client");
+    expect(entries[0]?.manifestKey).toBe("client.js");
+    expect(entries[0]?.sourceFile).toBe(join(workDir, "src/main.tsx"));
+    expect(entries[0]?.htmlPath).toBe("index.html");
+  });
+
+  test("clientEntry: sourceFile fehlt → throws", () => {
+    expect(() => resolveClientEntries(workDir, { clientEntry: "./src/missing.tsx" })).toThrow(
+      /kumiko\.clientEntry.*does not exist/s,
+    );
+  });
+
+  test("clientEntry with non-source extension throws even when the file exists", async () => {
+    await writeSourceFiles(["app.json"]);
+
+    expect(() => resolveClientEntries(workDir, { clientEntry: "./src/app.json" })).toThrow(
+      /kumiko\.clientEntry "\.\/src\/app\.json" must point to a \.ts, \.tsx, \.js or \.jsx file/,
+    );
+  });
+
+  test("clientEntry und clientEntries gleichzeitig → mutual-exclusion error", async () => {
+    await writeSourceFiles(["main.tsx", "client-admin.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntry: "./src/main.tsx",
+        clientEntries: [{ name: "admin", sourceFile: "./src/client-admin.tsx" }],
+      }),
+    ).toThrow(/mutually exclusive/);
+  });
+
+  test("clientEntries: leeres Array → throws", () => {
+    expect(() => resolveClientEntries(workDir, { clientEntries: [] })).toThrow(
+      /"kumiko\.clientEntries" is empty/,
+    );
+  });
+
+  test("clientEntries: ungültiger name (führender Großbuchstabe) → throws", async () => {
+    await writeSourceFiles(["client-admin.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "Admin", sourceFile: "./src/client-admin.tsx" }],
+      }),
+    ).toThrow(/invalid "kumiko\.clientEntries\[\]\.name"/);
+  });
+
+  test("clientEntries: name mit '..' → throws", async () => {
+    await writeSourceFiles(["client-admin.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "../x", sourceFile: "./src/client-admin.tsx" }],
+      }),
+    ).toThrow(/invalid "kumiko\.clientEntries\[\]\.name"/);
+  });
+
+  test("clientEntries: sourceFile escaping cwd via '..' → throws", () => {
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "admin", sourceFile: "../outside.tsx" }],
+      }),
+    ).toThrow(/resolves outside the app root/);
+  });
+
+  test("clientEntries: absolute sourceFile outside cwd → throws", () => {
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "admin", sourceFile: "/etc/passwd" }],
+      }),
+    ).toThrow(/resolves outside the app root/);
+  });
+
+  test("clientEntries: htmlPath escaping cwd → throws", async () => {
+    await writeSourceFiles(["client-admin.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [
+          { name: "admin", sourceFile: "./src/client-admin.tsx", htmlPath: "../outside.html" },
+        ],
+      }),
+    ).toThrow(/resolves outside the app root/);
+  });
+
+  test("clientEntries: sourceFile existiert nicht → throws", () => {
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "admin", sourceFile: "./src/client-admin.tsx" }],
+      }),
+    ).toThrow(/sourceFile ".*" does not exist/);
+  });
+
+  test("clientEntries: sourceFile with non-source extension throws even when the file exists", async () => {
+    await writeSourceFiles(["client-admin.css"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [{ name: "admin", sourceFile: "./src/client-admin.css" }],
+      }),
+    ).toThrow(
+      /kumiko\.clientEntries\["admin"\]\.sourceFile "\.\/src\/client-admin\.css" must point to a \.ts, \.tsx, \.js or \.jsx file/,
+    );
+  });
+
+  test("clientEntries: htmlPath with non-html extension throws", async () => {
+    await writeSourceFiles(["client-admin.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [
+          {
+            name: "admin",
+            sourceFile: "./src/client-admin.tsx",
+            htmlPath: "./public/manifest.json",
+          },
+        ],
+      }),
+    ).toThrow(
+      /kumiko\.clientEntries\["admin"\]\.htmlPath "\.\/public\/manifest\.json" must point to an \.html file/,
+    );
+  });
+
+  test("clientEntries: doppelter name → throws", async () => {
+    await writeSourceFiles(["client-admin.tsx", "client-admin2.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [
+          { name: "admin", sourceFile: "./src/client-admin.tsx" },
+          { name: "admin", sourceFile: "./src/client-admin2.tsx" },
+        ],
+      }),
+    ).toThrow(/duplicate "kumiko\.clientEntries\[\]\.name" "admin"/);
+  });
+
+  test("clientEntries: zwei Entries mit gleichem html-basename (default 'public' vs. explizit) → throws", async () => {
+    await writeSourceFiles(["client-public.tsx", "client-legacy.tsx"]);
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [
+          { name: "public", sourceFile: "./src/client-public.tsx" },
+          { name: "legacy", sourceFile: "./src/client-legacy.tsx", htmlPath: "./index.html" },
+        ],
+      }),
+    ).toThrow(/resolve to the same HTML output file "index\.html"/);
+  });
+
+  test("clientEntries: zwei Entries mit identischem source-basename → throws", async () => {
+    await mkdir(join(workDir, "src/admin"), { recursive: true });
+    await mkdir(join(workDir, "src/public"), { recursive: true });
+    await writeFile(join(workDir, "src/admin/index.tsx"), "// admin");
+    await writeFile(join(workDir, "src/public/index.tsx"), "// public");
+
+    expect(() =>
+      resolveClientEntries(workDir, {
+        clientEntries: [
+          { name: "admin", sourceFile: "./src/admin/index.tsx", htmlPath: "./admin.html" },
+          { name: "public", sourceFile: "./src/public/index.tsx" },
+        ],
+      }),
+    ).toThrow(/share the source basename "index"/);
+  });
+
+  test("publicstatus-Shape: public ohne htmlPath, admin/auth mit explizitem htmlPath", async () => {
+    await mkdir(join(workDir, "public"), { recursive: true });
+    await writeFile(join(workDir, "public/admin.html"), "<html></html>");
+    await writeFile(join(workDir, "public/auth.html"), "<html></html>");
+    await writeSourceFiles(["client-public.tsx", "client-admin.tsx", "client-auth.tsx"]);
+
+    const entries = resolveClientEntries(workDir, {
+      clientEntries: [
+        { name: "public", sourceFile: "./src/client-public.tsx" },
+        { name: "admin", sourceFile: "./src/client-admin.tsx", htmlPath: "./public/admin.html" },
+        { name: "auth", sourceFile: "./src/client-auth.tsx", htmlPath: "./public/auth.html" },
+      ],
+    });
+
+    expect(entries.map((e) => e.name)).toEqual(["admin", "auth", "public"]);
+    const publicEntry = entries.find((e) => e.name === "public");
+    expect(publicEntry?.manifestKey).toBe("client-public.js");
+    expect(publicEntry?.htmlPath).toBe("index.html");
+    const admin = entries.find((e) => e.name === "admin");
+    expect(admin?.manifestKey).toBe("client-admin.js");
+    expect(admin?.htmlPath).toBe(join(workDir, "public/admin.html"));
+    const auth = entries.find((e) => e.name === "auth");
+    expect(auth?.htmlPath).toBe(join(workDir, "public/auth.html"));
+  });
+
+  test("show-pony-Shape: admin und public beide mit explizitem htmlPath", async () => {
+    await mkdir(join(workDir, "public"), { recursive: true });
+    await writeFile(join(workDir, "public/admin.html"), "<html></html>");
+    await writeFile(join(workDir, "public/index.html"), "<html></html>");
+    await writeSourceFiles(["client-admin.tsx", "client-public.tsx"]);
+
+    const entries = resolveClientEntries(workDir, {
+      clientEntries: [
+        { name: "admin", sourceFile: "./src/client-admin.tsx", htmlPath: "./public/admin.html" },
+        { name: "public", sourceFile: "./src/client-public.tsx", htmlPath: "./public/index.html" },
+      ],
+    });
+
+    expect(entries.map((e) => e.manifestKey)).toEqual(["client-admin.js", "client-public.js"]);
+    expect(entries.map((e) => e.htmlPath)).toEqual([
+      join(workDir, "public/admin.html"),
+      join(workDir, "public/index.html"),
+    ]);
+  });
+
+  test("offlot-app-Shape: einziger Entry 'app' mit explizitem htmlPath", async () => {
+    await mkdir(join(workDir, "public"), { recursive: true });
+    await writeFile(join(workDir, "public/app.html"), "<html></html>");
+    await writeSourceFiles(["client-app.tsx"]);
+
+    const entries = resolveClientEntries(workDir, {
+      clientEntries: [
+        { name: "app", sourceFile: "./src/client-app.tsx", htmlPath: "./public/app.html" },
+      ],
+    });
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0]?.manifestKey).toBe("client-app.js");
+    expect(entries[0]?.htmlPath).toBe(join(workDir, "public/app.html"));
+  });
+});
+
+describe("build-prod-bundle/readClientEntriesConfig", () => {
+  let workDir = "";
+
+  beforeEach(async () => {
+    workDir = await mkdtemp(join(tmpdir(), "kumiko-build-config-"));
+  });
+
+  afterEach(async () => {
+    await rm(workDir, { recursive: true, force: true });
+  });
+
+  test("kein package.json → {}", () => {
+    expect(readClientEntriesConfig(workDir)).toEqual({});
+  });
+
+  test("package.json ohne kumiko-Block → {}", async () => {
+    await writeJson(join(workDir, "package.json"), { name: "app" });
+
+    expect(readClientEntriesConfig(workDir)).toEqual({});
+  });
+
+  test("valides kumiko.clientEntry", async () => {
+    await writeJson(join(workDir, "package.json"), {
+      name: "app",
+      kumiko: { clientEntry: "./src/client.tsx" },
+    });
+
+    expect(readClientEntriesConfig(workDir)).toEqual({ clientEntry: "./src/client.tsx" });
+  });
+
+  test("valides kumiko.clientEntries", async () => {
+    const declared: readonly ClientEntryDeclaration[] = [
+      { name: "public", sourceFile: "./src/client-public.tsx" },
+      { name: "admin", sourceFile: "./src/client-admin.tsx", htmlPath: "./public/admin.html" },
+    ];
+    await writeJson(join(workDir, "package.json"), {
+      name: "app",
+      kumiko: { clientEntries: declared },
+    });
+
+    expect(readClientEntriesConfig(workDir)).toEqual({ clientEntries: declared });
+  });
+
+  test("kumiko.clientEntry ist keine string → throws", async () => {
+    await writeJson(join(workDir, "package.json"), { name: "app", kumiko: { clientEntry: 42 } });
+
+    expect(() => readClientEntriesConfig(workDir)).toThrow(
+      /"kumiko\.clientEntry" must be a string/,
+    );
+  });
+
+  test("kumiko.clientEntries ist kein Array → throws", async () => {
+    await writeJson(join(workDir, "package.json"), {
+      name: "app",
+      kumiko: { clientEntries: { name: "admin" } },
+    });
+
+    expect(() => readClientEntriesConfig(workDir)).toThrow(
+      /"kumiko\.clientEntries" must be an array/,
+    );
+  });
+
+  test("kumiko.clientEntries[] ohne sourceFile → throws", async () => {
+    await writeJson(join(workDir, "package.json"), {
+      name: "app",
+      kumiko: { clientEntries: [{ name: "admin" }] },
+    });
+
+    expect(() => readClientEntriesConfig(workDir)).toThrow(
+      /"kumiko\.clientEntries\[0\]\.sourceFile" must be a non-empty string/,
+    );
+  });
+
+  test("kumiko.clientEntries[].htmlPath ist keine string → throws", async () => {
+    await writeJson(join(workDir, "package.json"), {
+      name: "app",
+      kumiko: {
+        clientEntries: [{ name: "admin", sourceFile: "./src/client-admin.tsx", htmlPath: 1 }],
+      },
+    });
+
+    expect(() => readClientEntriesConfig(workDir)).toThrow(
+      /"kumiko\.clientEntries\[0\]\.htmlPath" must be a string/,
+    );
+  });
+
+  test("kaputtes JSON → throws", async () => {
+    await writeFile(join(workDir, "package.json"), "{not json");
+
+    expect(() => readClientEntriesConfig(workDir)).toThrow(/Invalid JSON/);
+  });
+});
+
 describe("build-prod-bundle/injectAssetTags", () => {
   test("ersetzt /client.js durch hashed URL im script-tag", () => {
     const html = `<html><body><script type="module" src="/client.js"></script></body></html>`;
@@ -317,34 +672,22 @@ describe("build-prod-bundle/discovery edges", () => {
     await rm(workDir, { recursive: true, force: true });
   });
 
-  test("discoverClientEntries accepts src/client.ts (no x)", async () => {
+  test("resolveClientEntries accepts src/client.ts (no x)", async () => {
     await mkdir(join(workDir, "src"), { recursive: true });
     await writeFile(join(workDir, "src/client.ts"), "// single ts");
-    const entries = discoverClientEntries(workDir);
+    const entries = resolveClientEntries(workDir, {});
     expect(entries).toHaveLength(1);
     expect(entries[0]?.name).toBe("client");
     expect(entries[0]?.sourceFile.endsWith("src/client.ts")).toBe(true);
   });
 
-  test("discoverClientEntries ignores non-matching client-* names", async () => {
+  test("resolveClientEntries ignores non-matching legacy client-* names (no migration error)", async () => {
     await mkdir(join(workDir, "src"), { recursive: true });
     // Uppercase / leading digit / underscore violate ^client-([a-z][a-z0-9-]*)\.tsx?$
     await writeFile(join(workDir, "src/client-Admin.tsx"), "// bad");
     await writeFile(join(workDir, "src/client-1bad.tsx"), "// bad");
     await writeFile(join(workDir, "src/client_admin.tsx"), "// bad");
-    expect(discoverClientEntries(workDir)).toEqual([]);
-  });
-
-  // #2305: a module only imported by another client-*.tsx still matches
-  // the entry pattern and becomes a second bundle entry.
-  test("discoverClientEntries treats a plain imported module named client-<x>.tsx as its own entry", async () => {
-    await mkdir(join(workDir, "src"), { recursive: true });
-    await writeFile(join(workDir, "src/client-app.tsx"), "// real entry");
-    await writeFile(join(workDir, "src/client-features.tsx"), "export const clientFeatures = [];");
-
-    const entries = discoverClientEntries(workDir);
-
-    expect(entries.map((e) => e.name)).toEqual(["app", "features"]);
+    expect(resolveClientEntries(workDir, {})).toEqual([]);
   });
 });
 
@@ -358,25 +701,24 @@ describe("build-prod-bundle/buildMissingTemplateError", () => {
     };
   }
 
-  test("names the discovered source file and the client-<suffix> convention", () => {
+  test("names the declaring entry name and its sourceFile", () => {
     const message = buildMissingTemplateError(
       { "client-features.js": "/assets/client-features-abcd.js" },
       multiEntry(),
     );
 
     expect(message).toContain("src/client-features.tsx");
-    expect(message).toContain("client-<suffix>.tsx");
-    expect(message).toContain("umbenennen");
+    expect(message).toContain("kumiko.clientEntries");
+    expect(message).toContain('Entry "features"');
   });
 
-  test("single-mode entry gets no rename hint (nothing was auto-discovered by suffix)", () => {
+  test("single-mode entry gets no declaration hint", () => {
     const message = buildMissingTemplateError(
       { "client.js": "/assets/client-abcd.js" },
       clientEntry(),
     );
 
     expect(message).toContain("src/client.tsx");
-    expect(message).not.toContain("umbenennen");
-    expect(message).not.toContain("client-<suffix>.tsx");
+    expect(message).not.toContain("kumiko.clientEntries");
   });
 });

package/src/build-prod-bundle.ts

@@ -3,9 +3,16 @@
 // die App-Struktur, Bun.build + Tailwind + Public-Folder-Copy
 // produzieren ein deploybares dist/.
 //
-// Convention (alles optional, fehlt was → übersprungen):
+// Client entries (fw#2320 — explicit, no filename inference):
+//
+//   package.json "kumiko.clientEntries": [{ name, sourceFile, htmlPath? }]
+//                                     →  one Bun.build bundle per declared entry
+//   package.json "kumiko.clientEntry": "./src/…"
+//                                     →  single bundle, name "client"
+//   (neither declared)               →  convention: src/client.tsx | src/client.ts
+//
+// Convention for everything else (all optional, missing → skipped):
 //
-//   src/client.tsx | src/client.ts   →  Bun.build (splitting + hash + asset-loader)
 //   src/styles.css                   →  Tailwind one-shot
 //                                       (oder fallback auf @cosmicdrift/kumiko-renderer-web/styles.css
 //                                        wenn nur clientEntry da ist und kein eigenes CSS)
@@ -40,10 +47,11 @@
 //   alles andere (public/)  →  default (auto-cache)
 
 import { createHash } from "node:crypto";
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join, resolve } from "node:path";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { isPlainObject, parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "temporal-polyfill";
 import { canResolveTailwindStylesheet, resolveTailwindCli } from "./resolve-tailwind-cli";
 
@@ -62,6 +70,22 @@ export type BuildProdBundleOptions = {
    *  @cosmicdrift/kumiko-renderer-web/styles.css wenn clientEntry da ist.
    *  `false` deaktiviert die CSS-Pipeline explizit. */
   readonly stylesheet?: string | false;
+} & ClientEntriesConfig;
+
+/** One declared client entry, read from package.json `kumiko.clientEntries`.
+ *  `name` becomes the output filename (`client-<name>.js` / `<name>.html`
+ *  unless `htmlPath` overrides it). */
+export type ClientEntryDeclaration = {
+  readonly name: string;
+  readonly sourceFile: string;
+  readonly htmlPath?: string;
+};
+
+/** The two mutually exclusive shapes read from package.json `kumiko.*`.
+ *  Neither set → convention mode (src/client.tsx | src/client.ts). */
+export type ClientEntriesConfig = {
+  readonly clientEntry?: string;
+  readonly clientEntries?: readonly ClientEntryDeclaration[];
 };
 
 export type BuildManifest = Readonly<Record<string, string>>;
@@ -132,7 +156,7 @@ export async function buildProdBundle(options: BuildProdBundleOptions = {}): Pro
   const assetsDir = join(outDir, ASSETS_DIR);
 
   // 1. Discovery: was ist da?
-  const clientEntries = discoverClientEntries(cwd);
+  const clientEntries = resolveClientEntries(cwd, options);
   const firstClientSource = clientEntries[0]?.sourceFile;
   const stylesheet = resolveStylesheetEntry(cwd, firstClientSource, options.stylesheet);
   const publicDir = resolve(cwd, "public");
@@ -140,8 +164,8 @@ export async function buildProdBundle(options: BuildProdBundleOptions = {}): Pro
 
   if (clientEntries.length === 0 && !hasPublicDir) {
     throw new Error(
-      `[kumiko build] nothing to build in ${cwd} — expected at least one of: ` +
-        `src/client.tsx, src/client-*.tsx, public/`,
+      `[kumiko build] nothing to build in ${cwd} — expected one of: ` +
+        `package.json "kumiko.clientEntry"/"kumiko.clientEntries", src/client.tsx, public/`,
     );
   }
 
@@ -230,35 +254,166 @@ export async function buildProdBundle(options: BuildProdBundleOptions = {}): Pro
 
 // Single client-entry shape — one bundle, one html-template.
 export type ClientEntry = {
-  /** Logical name. "client" für single-mode; sonst der Suffix von
-   *  src/client-<suffix>.tsx (z.B. "public", "admin"). */
+  /** Logical name. "client" for single-entry mode (package.json
+   *  `kumiko.clientEntry` or the src/client.tsx convention); otherwise the
+   *  `name` declared in package.json `kumiko.clientEntries[]`. */
   readonly name: string;
-  /** TypeScript-Source. */
+  /** Absolute path to the TypeScript entry module. */
   readonly sourceFile: string;
-  /** Manifest-key & logical-asset-path. "client.js" für single, sonst
-   *  "client-<name>.js". */
+  /** Manifest key & logical asset path. "client.js" for single-entry mode,
+   *  otherwise "client-<name>.js". */
   readonly manifestKey: string;
-  /** HTML-template-Pfad relativ zum cwd. "index.html" für single oder
-   *  "public"-entry; sonst "<name>.html". Naming bewusst symmetrisch
-   *  zu `runDevApp.clientEntries[].htmlPath` damit Build und Dev-Server
-   *  dieselbe Konvention verwenden. */
+  /** HTML template path — absolute when declared or discovered on disk,
+   *  otherwise a bare default filename ("index.html", "<name>.html")
+   *  resolved against cwd by the caller. Naming is deliberately symmetric
+   *  to `runDevApp.clientEntries[].htmlPath` so build and dev server agree
+   *  on the same convention. */
   readonly htmlPath: string;
 };
 
-// @internal — exported nur für Unit-Tests. Konsumenten gehen über
-// buildProdBundle.
-//
-// Discovery-Pattern:
-//   - Falls `src/client-<suffix>.tsx` files existieren → multi-entry-mode,
-//     ein Bundle pro Datei. "public" mapped auf index.html (default),
-//     andere Suffixe auf "<suffix>.html".
-//   - Sonst falls `src/client.tsx` oder `src/client.ts` existiert →
-//     single-entry-mode mit name "client" + index.html.
-//   - Sonst leeres Array (keine Client-Bundles).
-export function discoverClientEntries(cwd: string): readonly ClientEntry[] {
-  const multi = discoverMultiClientEntries(cwd);
-  if (multi.length > 0) return multi;
+const ENTRY_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+// The extension guard and both basename derivations (collision check, Bun.build
+// output mapping) must agree, otherwise an accepted entry maps to no bundle.
+const SOURCE_EXTENSION_PATTERN = /\.(?:tsx?|jsx?)$/;
+
+/** Resolves the client entries to build. Public — also called from
+ *  `kumiko-build`/`kumiko build` via `@cosmicdrift/kumiko-dev-server/build`,
+ *  not just from unit tests.
+ *
+ * Precedence (fw#2320 — explicit declaration, no filename inference):
+ *   1. `declared.clientEntry` and `declared.clientEntries` both set → throw.
+ *   2. `declared.clientEntries` (non-empty) → one entry per declaration.
+ *   3. `declared.clientEntry` → single entry, name "client".
+ *   4. Neither → convention: src/client.tsx | src/client.ts (name "client").
+ *      If that convention finds nothing but src/ still has legacy
+ *      `client-<suffix>.tsx` files, throws a migration error instead of
+ *      silently shipping a build without their bundles. */
+export function resolveClientEntries(
+  cwd: string,
+  declared: ClientEntriesConfig,
+): readonly ClientEntry[] {
+  const hasClientEntry = declared.clientEntry !== undefined;
+  const hasClientEntries = declared.clientEntries !== undefined;
+  if (hasClientEntry && hasClientEntries) {
+    throw new Error(
+      '[kumiko build] package.json "kumiko.clientEntry" and "kumiko.clientEntries" ' +
+        "are mutually exclusive — declare only one.",
+    );
+  }
+  if (declared.clientEntries !== undefined) {
+    return resolveDeclaredMultiEntries(cwd, declared.clientEntries);
+  }
+  if (declared.clientEntry !== undefined) {
+    return [resolveDeclaredSingleEntry(cwd, declared.clientEntry)];
+  }
+  return resolveConventionEntries(cwd);
+}
 
+function resolveDeclaredMultiEntries(
+  cwd: string,
+  declarations: readonly ClientEntryDeclaration[],
+): readonly ClientEntry[] {
+  if (declarations.length === 0) {
+    throw new Error(
+      '[kumiko build] package.json "kumiko.clientEntries" is empty — omit the key ' +
+        "entirely to use the src/client.tsx convention.",
+    );
+  }
+  const entries = declarations.map((decl) => resolveDeclaredEntry(cwd, decl));
+
+  const seenNames = new Set<string>();
+  for (const entry of entries) {
+    if (seenNames.has(entry.name)) {
+      throw new Error(
+        `[kumiko build] duplicate "kumiko.clientEntries[].name" "${entry.name}" — names must be unique.`,
+      );
+    }
+    seenNames.add(entry.name);
+  }
+
+  const seenHtmlBasenames = new Set<string>();
+  for (const entry of entries) {
+    const base = basenameOf(entry.htmlPath);
+    if (seenHtmlBasenames.has(base)) {
+      throw new Error(
+        `[kumiko build] two "kumiko.clientEntries" entries resolve to the same HTML ` +
+          `output file "${base}" — set an explicit "htmlPath" on one of them.`,
+      );
+    }
+    seenHtmlBasenames.add(base);
+  }
+
+  // Bun.build's output → ClientEntry mapping (buildClientBundles) matches on
+  // the source basename without extension. Two entries sharing it would
+  // silently map to the same bundle.
+  const seenSourceBasenames = new Set<string>();
+  for (const entry of entries) {
+    const base = basenameOf(entry.sourceFile).replace(SOURCE_EXTENSION_PATTERN, "");
+    if (seenSourceBasenames.has(base)) {
+      throw new Error(
+        `[kumiko build] two "kumiko.clientEntries" entries share the source basename ` +
+          `"${base}" ("${entry.sourceFile}") — rename one of the source files.`,
+      );
+    }
+    seenSourceBasenames.add(base);
+  }
+
+  return [...entries].sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function resolveDeclaredEntry(cwd: string, decl: ClientEntryDeclaration): ClientEntry {
+  if (!ENTRY_NAME_PATTERN.test(decl.name)) {
+    throw new Error(
+      `[kumiko build] invalid "kumiko.clientEntries[].name" "${decl.name}" — must match ` +
+        `^[a-z][a-z0-9-]*$ (it becomes the output filename client-${decl.name}.js).`,
+    );
+  }
+  const sourceFile = resolveWithinCwd(
+    cwd,
+    decl.sourceFile,
+    `kumiko.clientEntries["${decl.name}"].sourceFile`,
+  );
+  assertValidSourceExtension(decl.sourceFile, `kumiko.clientEntries["${decl.name}"].sourceFile`);
+  if (!isExistingFile(sourceFile)) {
+    throw new Error(
+      `[kumiko build] kumiko.clientEntries["${decl.name}"].sourceFile "${decl.sourceFile}" ` +
+        `does not exist (resolved: ${sourceFile}).`,
+    );
+  }
+  const htmlPath =
+    decl.htmlPath !== undefined
+      ? resolveDeclaredHtmlPath(cwd, decl.name, decl.htmlPath)
+      : decl.name === "public"
+        ? (discoverHtmlTemplateFor(cwd, "index") ?? "index.html")
+        : (discoverHtmlTemplateFor(cwd, decl.name) ?? `${decl.name}.html`);
+  return { name: decl.name, sourceFile, manifestKey: `client-${decl.name}.js`, htmlPath };
+}
+
+function resolveDeclaredHtmlPath(cwd: string, entryName: string, htmlPath: string): string {
+  const label = `kumiko.clientEntries["${entryName}"].htmlPath`;
+  const resolved = resolveWithinCwd(cwd, htmlPath, label);
+  assertValidHtmlExtension(htmlPath, label);
+  return resolved;
+}
+
+function resolveDeclaredSingleEntry(cwd: string, clientEntry: string): ClientEntry {
+  const sourceFile = resolveWithinCwd(cwd, clientEntry, "kumiko.clientEntry");
+  assertValidSourceExtension(clientEntry, "kumiko.clientEntry");
+  if (!isExistingFile(sourceFile)) {
+    throw new Error(
+      `[kumiko build] kumiko.clientEntry "${clientEntry}" does not exist (resolved: ${sourceFile}).`,
+    );
+  }
+  return {
+    name: "client",
+    sourceFile,
+    manifestKey: "client.js",
+    htmlPath: discoverHtmlTemplateFor(cwd, "index") ?? "index.html",
+  };
+}
+
+function resolveConventionEntries(cwd: string): readonly ClientEntry[] {
   for (const candidate of ["src/client.tsx", "src/client.ts"]) {
     const sourceFile = resolve(cwd, candidate);
     if (existsSync(sourceFile)) {
@@ -272,10 +427,19 @@ export function discoverClientEntries(cwd: string): readonly ClientEntry[] {
       ];
     }
   }
+  const legacyEntries = findLegacyClientFiles(cwd);
+  if (legacyEntries.length > 0) {
+    throw new Error(buildLegacyMultiEntryMigrationError(legacyEntries));
+  }
   return [];
 }
 
-function discoverMultiClientEntries(cwd: string): readonly ClientEntry[] {
+type LegacyClientFile = { readonly name: string; readonly file: string };
+
+// Pre-fw#2320 multi-entry convention: any src/client-<suffix>.tsx(x) became
+// its own bundle. Detecting these without a declaration means an unmigrated
+// app would silently ship without their bundles — throw instead.
+function findLegacyClientFiles(cwd: string): readonly LegacyClientFile[] {
   const srcDir = resolve(cwd, "src");
   if (!existsSync(srcDir)) return [];
   let files: readonly string[];
@@ -284,25 +448,122 @@ function discoverMultiClientEntries(cwd: string): readonly ClientEntry[] {
   } catch {
     return [];
   }
-  const out: ClientEntry[] = [];
+  const found: LegacyClientFile[] = [];
   for (const file of files) {
     const match = /^client-([a-z][a-z0-9-]*)\.tsx?$/.exec(file);
-    const suffix = match?.[1];
-    if (!suffix) continue;
-    const sourceFile = resolve(srcDir, file);
-    out.push({
-      name: suffix,
-      sourceFile,
-      manifestKey: `client-${suffix}.js`,
-      // "public"-entry serviert die default-page (index.html), sonst pro
-      // Suffix ein eigenes Template.
-      htmlPath:
-        suffix === "public"
-          ? (discoverHtmlTemplateFor(cwd, "index") ?? "index.html")
-          : (discoverHtmlTemplateFor(cwd, suffix) ?? `${suffix}.html`),
-    });
+    if (match?.[1]) found.push({ name: match[1], file });
+  }
+  return found.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function buildLegacyMultiEntryMigrationError(entries: readonly LegacyClientFile[]): string {
+  const fileNames = entries.map((e) => `src/${e.file}`).join(", ");
+  const snippet = entries
+    .map((e) => `      { "name": "${e.name}", "sourceFile": "./src/${e.file}" }`)
+    .join(",\n");
+  return (
+    `[kumiko build] found ${fileNames} but no "kumiko.clientEntries" declaration in ` +
+    `package.json — production builds no longer infer entries from filenames (fw#2320). Add:\n\n` +
+    `  "kumiko": {\n` +
+    `    "clientEntries": [\n` +
+    `${snippet}\n` +
+    `    ]\n` +
+    `  }\n`
+  );
+}
+
+function resolveWithinCwd(cwd: string, value: string, label: string): string {
+  const resolved = resolve(cwd, value);
+  const rel = relative(cwd, resolved);
+  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`[kumiko build] ${label} "${value}" resolves outside the app root ${cwd}.`);
+  }
+  return resolved;
+}
+
+function isExistingFile(path: string): boolean {
+  return existsSync(path) && statSync(path).isFile();
+}
+
+// The basename of htmlPath becomes a dist output filename (e.g. "manifest.json"
+// would collide with a file the build writes itself) — restrict it to .html.
+function assertValidHtmlExtension(value: string, label: string): void {
+  if (!value.endsWith(".html")) {
+    throw new Error(`[kumiko build] ${label} "${value}" must point to an .html file.`);
+  }
+}
+
+function assertValidSourceExtension(value: string, label: string): void {
+  if (!SOURCE_EXTENSION_PATTERN.test(value)) {
+    throw new Error(
+      `[kumiko build] ${label} "${value}" must point to a .ts, .tsx, .js or .jsx file.`,
+    );
+  }
+}
+
+/** Reads package.json → `kumiko.clientEntry` / `kumiko.clientEntries`.
+ *  Missing file or missing keys → `{}` (falls back to convention mode). A
+ *  malformed value under either key throws — a typo here must fail the
+ *  build loudly instead of silently dropping declared entries. */
+export function readClientEntriesConfig(cwd: string): ClientEntriesConfig {
+  const pkgJsonPath = resolve(cwd, "package.json");
+  if (!existsSync(pkgJsonPath)) return {};
+  const raw = readFileSync(pkgJsonPath, "utf8");
+  const parsed = parseJsonOrThrow<unknown>(raw, pkgJsonPath);
+  if (!isPlainObject(parsed)) return {};
+  const kumiko = parsed["kumiko"];
+  if (!isPlainObject(kumiko)) return {};
+
+  const result: { clientEntry?: string; clientEntries?: readonly ClientEntryDeclaration[] } = {};
+
+  if ("clientEntry" in kumiko) {
+    const value = kumiko["clientEntry"];
+    if (typeof value !== "string") {
+      throw new Error(
+        `[kumiko build] package.json "kumiko.clientEntry" must be a string, got ${typeof value}.`,
+      );
+    }
+    result.clientEntry = value;
+  }
+
+  if ("clientEntries" in kumiko) {
+    const value = kumiko["clientEntries"];
+    if (!Array.isArray(value)) {
+      throw new Error(
+        `[kumiko build] package.json "kumiko.clientEntries" must be an array, got ${typeof value}.`,
+      );
+    }
+    result.clientEntries = value.map((item, index) => parseClientEntryDeclaration(item, index));
+  }
+
+  return result;
+}
+
+function parseClientEntryDeclaration(item: unknown, index: number): ClientEntryDeclaration {
+  if (!isPlainObject(item)) {
+    throw new Error(
+      `[kumiko build] package.json "kumiko.clientEntries[${index}]" must be an object.`,
+    );
   }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
+  const name = item["name"];
+  const sourceFile = item["sourceFile"];
+  const htmlPath = item["htmlPath"];
+  if (typeof name !== "string" || name.length === 0) {
+    throw new Error(
+      `[kumiko build] package.json "kumiko.clientEntries[${index}].name" must be a non-empty string.`,
+    );
+  }
+  if (typeof sourceFile !== "string" || sourceFile.length === 0) {
+    throw new Error(
+      `[kumiko build] package.json "kumiko.clientEntries[${index}].sourceFile" must be a non-empty string.`,
+    );
+  }
+  if (htmlPath !== undefined && typeof htmlPath !== "string") {
+    throw new Error(
+      `[kumiko build] package.json "kumiko.clientEntries[${index}].htmlPath" must be a string when set.`,
+    );
+  }
+  return { name, sourceFile, ...(htmlPath !== undefined && { htmlPath }) };
 }
 
 function discoverHtmlTemplateFor(cwd: string, basename: string): string | undefined {
@@ -475,7 +736,10 @@ async function buildClientBundles(
   // entry-output zurück auf seinen ClientEntry via Basename-match.
   const result: Record<string, string> = {};
   for (const entry of entries) {
-    const baseName = (entry.sourceFile.split("/").pop() ?? "").replace(/\.tsx?$/, "");
+    const baseName = (entry.sourceFile.split("/").pop() ?? "").replace(
+      SOURCE_EXTENSION_PATTERN,
+      "",
+    );
     const match = entryOutputs.find((o) => {
       const outName = o.path.split("/").pop() ?? "";
       return outName.startsWith(`${baseName}-`);
@@ -537,7 +801,8 @@ async function renderHtml(
 }
 
 // @internal — exported for unit tests only. See #2305: the message must
-// name the source file and the filename convention.
+// name the source file and, for a declared multi-entry, which package.json
+// "kumiko.clientEntries" entry it came from.
 export function buildMissingTemplateError(manifest: BuildManifest, entry: ClientEntry): string {
   const cssLine = manifest["styles.css"]
     ? `    <link rel="stylesheet" href="/styles.css" />\n`
@@ -548,15 +813,11 @@ export function buildMissingTemplateError(manifest: BuildManifest, entry: Client
     : "";
   const sourceBasename = basenameOf(entry.sourceFile);
   // Single-mode entries always carry manifestKey "client.js"; any other
-  // value came from discoverMultiClientEntries' filename match.
+  // value came from a declared package.json "kumiko.clientEntries" entry.
   const isMultiEntry = entry.manifestKey !== "client.js";
   const discoveryHint = isMultiEntry
-    ? `"src/${sourceBasename}" wurde automatisch als eigener Bundle-Entry erkannt — ` +
-      `jede Datei nach dem Muster src/client-<suffix>.tsx zählt als Entry (hier: Suffix "${entry.name}"). ` +
-      `War das nicht beabsichtigt, z. B. weil die Datei nur ein von einem anderen client-*.tsx ` +
-      `importiertes Modul ist: Datei umbenennen (ohne "client-"-Präfix), dann verschwindet der Entry.\n` +
-      `\n` +
-      `War es beabsichtigt:\n`
+    ? `Entry "${entry.name}" comes from package.json "kumiko.clientEntries" ` +
+      `(sourceFile: "src/${sourceBasename}").\n\n`
     : "";
   return (
     `[kumiko build] kein ${entry.htmlPath} gefunden für Entry "src/${sourceBasename}", ` +

package/src/changes.json

@@ -1,4 +1,18 @@
 [
+  {
+    "version": "0.323.0",
+    "type": "breaking",
+    "title": "buildProdBundle takes client entries explicitly via package.json \"kumiko.clientEntries\"/\"kumiko.clientEntry\" — no more filename inference",
+    "detail": "`discoverClientEntries(cwd)`, which scanned `src/` for\n`client-<suffix>.tsx` files and treated every match as its own bundle\nentry, is replaced by `resolveClientEntries(cwd, declared)` plus\n`readClientEntriesConfig(cwd)`, a boundary parser for package.json\n`kumiko.clientEntry` / `kumiko.clientEntries`. `buildProdBundle(options)`\nnow accepts the same `clientEntry`/`clientEntries` shape directly.\n\n`kumiko.clientEntries` entries are validated: `name` must match\n`^[a-z][a-z0-9-]*$` (it becomes the output filename), `sourceFile` (and\n`htmlPath`, if set) must resolve inside the app root, `sourceFile` must\nexist, and names/html-output-files/source-basenames must be unique\nacross the list. `clientEntry` and `clientEntries` are mutually\nexclusive; an empty `clientEntries` array is rejected (omit the key\ninstead). Apps with only `src/client.tsx` or `src/client.ts` need no\ndeclaration — that convention is unchanged.",
+    "migration": "Apps with `src/client-<name>.tsx` entries: add the entry list to\npackage.json, using the same objects already passed to\n`runDevApp`/`createKumikoServer`'s `clientEntries` (paths relative to the\napp root). Without this, the build now throws instead of silently\nbuilding without those bundles.\n\n  publicstatus:\n\n    \"kumiko\": {\n      \"clientEntries\": [\n        { \"name\": \"public\", \"sourceFile\": \"./src/client-public.tsx\" },\n        { \"name\": \"admin\", \"sourceFile\": \"./src/client-admin.tsx\", \"htmlPath\": \"./public/admin.html\" },\n        { \"name\": \"auth\", \"sourceFile\": \"./src/client-auth.tsx\", \"htmlPath\": \"./public/auth.html\" }\n      ]\n    }\n\n  show-pony:\n\n    \"kumiko\": {\n      \"clientEntries\": [\n        { \"name\": \"admin\", \"sourceFile\": \"./src/client-admin.tsx\", \"htmlPath\": \"./public/admin.html\" },\n        { \"name\": \"public\", \"sourceFile\": \"./src/client-public.tsx\", \"htmlPath\": \"./public/index.html\" }\n      ]\n    }\n\n  offlot-app:\n\n    \"kumiko\": {\n      \"clientEntries\": [\n        { \"name\": \"app\", \"sourceFile\": \"./src/client-app.tsx\", \"htmlPath\": \"./public/app.html\" }\n      ]\n    }\n\nApps using a single entry that isn't `src/client.tsx`: add\n`\"kumiko\": { \"clientEntry\": \"./src/…\" }` instead.\n\nApps with only `src/client.tsx` | `src/client.ts`: no action needed.\n\n`discoverClientEntries` (exported from\n`@cosmicdrift/kumiko-dev-server/build`) is removed; callers use\n`resolveClientEntries(cwd, readClientEntriesConfig(cwd))`."
+  },
+  {
+    "version": "0.323.0",
+    "type": "improvement",
+    "title": "runProdApp wires auth-email-password's new invite-info query into invite.infoHandler",
+    "detail": "When the invite feature is enabled, runProdApp now passes AuthQueries.inviteInfo as invite.infoHandler, mounting POST /auth/invite-info automatically.",
+    "migration": "No action needed: purely additive wiring, no option changes."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",

package/src/run-prod-app.ts

@@ -46,6 +46,7 @@ import {
   AuthHandlers,
   type AuthMailLocale,
   type AuthPaths,
+  AuthQueries,
   type EmailVerificationOptions,
   type InviteOptions,
   type PasswordResetOptions,
@@ -1168,6 +1169,7 @@ export async function runProdApp(options: RunProdAppOptions): Promise<ProdAppHan
             acceptHandler: AuthHandlers.inviteAccept,
             acceptWithLoginHandler: AuthHandlers.inviteAcceptWithLogin,
             signupCompleteHandler: AuthHandlers.inviteSignupComplete,
+            infoHandler: AuthQueries.inviteInfo,
           },
         }),
       },