@cosmicdrift/kumiko-bundled-features 0.71.0 → 0.73.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.71.0",
+  "version": "0.73.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -84,11 +84,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.71.0",
-    "@cosmicdrift/kumiko-framework": "0.71.0",
-    "@cosmicdrift/kumiko-headless": "0.71.0",
-    "@cosmicdrift/kumiko-renderer": "0.71.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.71.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.73.0",
+    "@cosmicdrift/kumiko-framework": "0.73.0",
+    "@cosmicdrift/kumiko-headless": "0.73.0",
+    "@cosmicdrift/kumiko-renderer": "0.73.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.73.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",
@@ -108,5 +108,8 @@
     "src",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "devDependencies": {
+    "@testing-library/user-event": "^14.6.1"
+  }
 }

package/src/auth-email-password/feature.ts

@@ -128,6 +128,22 @@ export function createAuthEmailPasswordFeature(
     r.describe(
       "Provides email+password authentication: the always-on handlers are `login`, `changePassword`, and `logout`; optional flows \u2014 password reset, email verification, magic-link self-signup, and tenant invite \u2014 are registered only when you pass their respective option objects (`passwordReset`, `emailVerification`, `signup`, `invite`) to `createAuthEmailPasswordFeature(opts)`. Each opt-in flow uses HMAC-signed or opaque-random tokens delivered via callback (e.g. `sendResetEmail`) so the feature stays transport-agnostic. Requires the `user` and `tenant` features, and declares `JWT_SECRET` (\u2265 32 chars) in `authEmailPasswordEnvSchema` so a missing secret surfaces at boot validation rather than on the first login attempt.",
     );
+    r.uiHints({
+      displayLabel: "Auth \u00b7 Email + Password",
+      category: "identity",
+      recommended: true,
+      configurableOptions: [
+        { key: "passwordReset", label: "Password-Reset-Flow", type: "boolean", default: true },
+        {
+          key: "emailVerification",
+          label: "Email-Verification-Flow",
+          type: "boolean",
+          default: true,
+        },
+        { key: "signup", label: "Self-Signup-Flow", type: "boolean", default: false },
+        { key: "invite", label: "Tenant-Invite-Flow", type: "boolean", default: false },
+      ],
+    });
     r.requires("user");
     r.requires("tenant");
     r.envSchema(authEmailPasswordEnvSchema);

package/src/billing-foundation/feature.ts

@@ -74,6 +74,11 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
   r.describe(
     "Plugin host for subscription billing \u2014 manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookHandler` factory for the `/api/subscription/webhook/:providerName` route. Low-level building block \u2014 use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
   );
+  r.uiHints({
+    displayLabel: "Billing \u00b7 Foundation",
+    category: "billing",
+    recommended: false,
+  });
   // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
   // shape (= subscription-state-snapshot); der event-type taggt was
   // passiert ist. Future-consumer (billing-history, accounting)

package/src/custom-fields/web/__tests__/custom-fields-form-section.test.tsx

@@ -6,7 +6,8 @@ import {
   PrimitivesProvider,
 } from "@cosmicdrift/kumiko-renderer";
 import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
-import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import type { ReactNode } from "react";
 import { CustomFieldsFormSection } from "../custom-fields-form-section";
 import { defaultTranslations } from "../i18n";
@@ -51,6 +52,7 @@ function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
 
 describe("CustomFieldsFormSection", () => {
   test("renders an input per matching fieldDefinition and dispatches set-custom-field on save", async () => {
+    const user = userEvent.setup();
     mockedQueryRows = [
       {
         id: "f1",
@@ -94,10 +96,10 @@ describe("CustomFieldsFormSection", () => {
     expect(document.getElementById("custom-field-rootCause")).toBeNull();
 
     // Type in vendor; tier left empty (should be skipped on save).
-    fireEvent.change(vendorInput, { target: { value: "Hetzner" } });
+    await user.type(vendorInput, "Hetzner");
 
     const saveBtn = screen.getByTestId("custom-fields-form-save");
-    fireEvent.click(saveBtn);
+    await user.click(saveBtn);
     // waitFor statt fester Promise.resolve()-Ticks — robust gegen zusätzliche
     // Microtasks im async handleSave-Loop (z.B. ein neuer dispatch-Wrapper).
     await waitFor(() => expect(dispatchSpy).toHaveBeenCalledTimes(1));
@@ -111,6 +113,7 @@ describe("CustomFieldsFormSection", () => {
   });
 
   test("pre-fills inputs from initialValues (Edit zeigt den Bestand, nicht write-only)", async () => {
+    const user = userEvent.setup();
     mockedQueryRows = [
       {
         id: "f1",
@@ -153,12 +156,11 @@ describe("CustomFieldsFormSection", () => {
     expect(saveBtn.disabled).toBe(true);
 
     // Nur das geänderte Feld wird geschrieben, nicht der unveränderte Bestand.
-    fireEvent.change(vendorInput, { target: { value: "Netcup" } });
+    await user.clear(vendorInput);
+    await user.type(vendorInput, "Netcup");
     expect(saveBtn.disabled).toBe(false);
-    fireEvent.click(saveBtn);
-    await Promise.resolve();
-    await Promise.resolve();
-    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    await user.click(saveBtn);
+    await waitFor(() => expect(dispatchSpy).toHaveBeenCalledTimes(1));
     expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:set-custom-field", {
       entityName: "component",
       entityId: "row-42",
@@ -237,6 +239,7 @@ describe("CustomFieldsFormSection", () => {
 
 describe("CustomFieldsFormSection — clear-Pfad", () => {
   test("Leeren eines gespeicherten Werts dispatched clear-custom-field (nicht skip)", async () => {
+    const user = userEvent.setup();
     mockedQueryRows = [
       {
         id: "f1",
@@ -262,12 +265,9 @@ describe("CustomFieldsFormSection — clear-Pfad", () => {
     const vendorInput = document.getElementById("custom-field-vendor") as HTMLInputElement;
     expect(vendorInput.value).toBe("Hetzner");
 
-    fireEvent.change(vendorInput, { target: { value: "" } });
-    fireEvent.click(screen.getByTestId("custom-fields-form-save"));
-    await Promise.resolve();
-    await Promise.resolve();
-
-    expect(dispatchSpy).toHaveBeenCalledTimes(1);
+    await user.clear(vendorInput);
+    await user.click(screen.getByTestId("custom-fields-form-save"));
+    await waitFor(() => expect(dispatchSpy).toHaveBeenCalledTimes(1));
     expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:clear-custom-field", {
       entityName: "component",
       entityId: "row-42",
@@ -276,6 +276,7 @@ describe("CustomFieldsFormSection — clear-Pfad", () => {
   });
 
   test("unveränderter Bestandswert wird beim Save NICHT erneut geschrieben", async () => {
+    const user = userEvent.setup();
     mockedQueryRows = [
       {
         id: "f1",
@@ -300,18 +301,16 @@ describe("CustomFieldsFormSection — clear-Pfad", () => {
 
     const vendorInput = document.getElementById("custom-field-vendor") as HTMLInputElement;
     // Tippen + zurück auf den Bestandswert → nicht dirty, kein Write.
-    fireEvent.change(vendorInput, { target: { value: "Hetzner2" } });
-    fireEvent.change(vendorInput, { target: { value: "Hetzner" } });
-    fireEvent.click(screen.getByTestId("custom-fields-form-save"));
-    await Promise.resolve();
-    await Promise.resolve();
-
-    expect(dispatchSpy).not.toHaveBeenCalled();
+    await user.type(vendorInput, "2");
+    await user.type(vendorInput, "{Backspace}");
+    await user.click(screen.getByTestId("custom-fields-form-save"));
+    await waitFor(() => expect(dispatchSpy).not.toHaveBeenCalled());
   });
 });
 
 describe("CustomFieldsFormSection — boolean/date-Pfade", () => {
   test("boolean: Bestand wird als true/false-String angezeigt, Save coerced zu boolean", async () => {
+    const user = userEvent.setup();
     mockedQueryRows = [
       {
         id: "f1",
@@ -340,17 +339,16 @@ describe("CustomFieldsFormSection — boolean/date-Pfade", () => {
     if (checkbox === null) throw new Error("boolean checkbox not rendered");
     expect(checkbox.getAttribute("aria-checked")).toBe("true");
 
-    fireEvent.click(checkbox);
-    fireEvent.click(screen.getByTestId("custom-fields-form-save"));
-    await Promise.resolve();
-    await Promise.resolve();
-
-    expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:set-custom-field", {
-      entityName: "component",
-      entityId: "row-42",
-      fieldKey: "active",
-      value: false,
-    });
+    await user.click(checkbox);
+    await user.click(screen.getByTestId("custom-fields-form-save"));
+    await waitFor(() =>
+      expect(dispatchSpy).toHaveBeenCalledWith("custom-fields:write:set-custom-field", {
+        entityName: "component",
+        entityId: "row-42",
+        fieldKey: "active",
+        value: false,
+      }),
+    );
   });
 
   test("date: Bestand erreicht das DateInput-Textfeld (locale-numerisch)", () => {

package/src/delivery/feature.ts

@@ -18,6 +18,11 @@ export function createDeliveryFeature(): FeatureDefinition {
     r.describe(
       "The notification dispatch core: call `ctx.notify(notificationType, { to, route, data, priority, idempotencyKey })` from any handler to fan out a notification across all registered channels (email, in-app, push). It stores per-user channel preferences in the `notification-preference` entity, logs every attempt to `read_delivery_attempts`, and enforces idempotency and rate-limiting \u2014 add `channel-email`, `channel-in-app`, or `channel-push` on top to actually send anything.",
     );
+    r.uiHints({
+      displayLabel: "Notifications \u00b7 Dispatch Core",
+      category: "notifications",
+      recommended: true,
+    });
     r.systemScope();
     // Backing table: the (tenant,user,type,channel) uniqueIndex lives only on
     // the physical table, not on the entity fields, so the generator would

package/src/feature-toggles/feature.ts

@@ -40,6 +40,11 @@ export function createFeatureTogglesFeature(
     r.describe(
       'Persists per-feature enabled/disabled state in the `read_global_feature_state` table and exposes a `set` write-handler plus `list`/`registered` query-handlers so operators can flip features at runtime without redeploying. Each API instance keeps an in-memory `GlobalFeatureToggleRuntime` snapshot (initialize it via `createFeatureToggleRuntime`, pass a `() => runtime` accessor to `createFeatureTogglesFeature`) that the dispatcher gate reads on every request; a `toggle-cache-sync` multi-stream projection with `delivery: "per-instance"` syncs the snapshot across instances whenever a `toggle-set` event is appended.',
     );
+    r.uiHints({
+      displayLabel: "Feature Toggles · Operator Switches",
+      category: "operations",
+      recommended: false,
+    });
     r.systemScope();
 
     // Toggle-change domain event. The event ends up in the events-table

package/src/mail-foundation/__tests__/mail-foundation.integration.test.ts

@@ -32,6 +32,7 @@ import { ConfigHandlers } from "../../config/constants";
 import { createConfigAccessorFactory } from "../../config/feature";
 import { type ConfigResolver, createConfigResolver } from "../../config/resolver";
 import { configValuesTable } from "../../config/table";
+import { clearInbox, getInbox, mailTransportInMemoryFeature } from "../../mail-transport-inmemory";
 import { mailTransportSmtpFeature, SMTP_PASSWORD } from "../../mail-transport-smtp";
 import { createSecretsContext, createSecretsFeature, tenantSecretsTable } from "../../secrets";
 import { createTenantFeature } from "../../tenant/feature";
@@ -58,6 +59,22 @@ const testProbeFeature = defineFeature("mail-test", (r) => {
       },
     }),
   );
+  r.writeHandler(
+    defineWriteHandler({
+      name: "send",
+      schema: z.object({ to: z.string(), subject: z.string(), html: z.string() }),
+      access: { roles: ["TenantAdmin", "SystemAdmin"] },
+      handler: async (event, ctx) => {
+        const transport = await createTransportForTenant(
+          ctx,
+          event.user.tenantId,
+          "mail-test:write:send",
+        );
+        await transport.send(event.payload);
+        return { isSuccess: true, data: {} };
+      },
+    }),
+  );
 });
 
 // --- Setup ---
@@ -91,6 +108,7 @@ beforeAll(async () => {
       createSecretsFeature(),
       mailFoundationFeature,
       mailTransportSmtpFeature,
+      mailTransportInMemoryFeature,
       testProbeFeature,
     ],
     masterKeyProvider: providerRef,
@@ -251,3 +269,18 @@ describe("scenario 3: tenant isolation", () => {
     expect(b["hasSend"]).toBe(true);
   });
 });
+
+// --- Scenario 4: the in-memory transport plugin actually delivers ---
+
+describe("scenario 4: in-memory transport dispatch", () => {
+  test("provider=inmemory → a sent mail lands in that tenant's inbox", async () => {
+    const admin = adminFor(406);
+    clearInbox(admin.tenantId);
+    await setConfig(admin, "mail-foundation:config:provider", "inmemory");
+
+    const message = { to: "user@acme.test", subject: "Hi", html: "<p>hello</p>" };
+    await stack.http.writeOk("mail-test:write:send", message, admin);
+
+    expect(getInbox(admin.tenantId)).toEqual([message]);
+  });
+});

package/src/rate-limiting/__tests__/rate-limiting.integration.test.ts

@@ -71,6 +71,17 @@ describe("rate-limiting feature — status query", () => {
     expect(status.remaining).toBe(2);
   });
 
+  test("blocks with 429 once the bucket is drained", async () => {
+    // The status query only *reports* state; this proves enforcement —
+    // the L3 hook actually rejects traffic over the limit, not just counts.
+    for (let i = 0; i < 5; i++) {
+      const ok = await stack.http.query("rl-probe:query:ping", {}, admin);
+      expect(ok.status).toBe(200);
+    }
+    const blocked = await stack.http.query("rl-probe:query:ping", {}, admin);
+    expect(blocked.status).toBe(429);
+  });
+
   test("status access requires Admin/SystemAdmin", async () => {
     const guest = TestUsers.user;
     const res = await stack.http.query(

package/src/sessions/feature.ts

@@ -43,6 +43,11 @@ export function createSessionsFeature(options?: SessionsFeatureOptions): Feature
     r.describe(
       "Tracks signed-in clients in the `read_user_sessions` table (one row per JWT, keyed by the `sid`/`jti` claim) and exposes handlers for `mine` (list your sessions), `revoke`, and `revokeAllOthers`. Session creation and revocation on the hot auth path are handled by `createSessionCallbacks()`, wired into `buildServer({ auth: { ... } })` outside the dispatcher; the feature also ships a manual-trigger cleanup job for pruning expired rows and an optional `autoRevokeOnPasswordChange` hook that mass-revokes all sessions for a user whenever their `passwordHash` changes.",
     );
+    r.uiHints({
+      displayLabel: "Sessions · Server-side Logout",
+      category: "identity",
+      recommended: false,
+    });
     // sessionChecker reads read_users on every authenticated request (status
     // gate for locked accounts) — make that a boot-time dependency so a
     // sessions-without-user wiring fails validateBoot instead of 500ing live.

package/src/tenant/__tests__/tenant.integration.test.ts

@@ -368,3 +368,68 @@ describe("scenario 7: access rules on handlers", () => {
     });
   });
 });
+
+// --- Scenario 8: entityList/entityEdit convention QNs ---
+//
+// The SystemAdmin tenant-list/tenant-edit screens resolve data through the
+// entity-suffixed convention QNs (tenant:query:tenant:{list,detail},
+// tenant:write:tenant:update), which were added alongside the legacy
+// tenant:query:list / tenant:write:update handlers. The boot-validator does NOT
+// check that an entityEdit has a matching update/detail handler, so this is the
+// only thing that proves the screens have a live data path. Literal QNs on
+// purpose — they ARE the wire contract the renderer computes.
+
+describe("scenario 8: entityList/entityEdit convention QNs", () => {
+  test("tenant:query:tenant:list returns all tenants for SystemAdmin (systemScope)", async () => {
+    const result = await stack.http.queryOk<{ rows: Record<string, unknown>[] }>(
+      "tenant:query:tenant:list",
+      {},
+      systemAdmin,
+    );
+    // acme + beta exist from earlier scenarios — systemScope yields all tenants.
+    expect(result.rows.length).toBeGreaterThanOrEqual(2);
+    expect(result.rows.map((r) => r["key"])).toEqual(expect.arrayContaining(["acme", "beta"]));
+  });
+
+  test("tenant:query:tenant:detail + tenant:write:tenant:update round-trip (entityEdit save persists)", async () => {
+    const created = await stack.http.writeOk(
+      "tenant:write:create",
+      { key: "delta", name: "Delta" },
+      systemAdmin,
+    );
+    const id = (created!["data"] as Record<string, unknown>)["id"] as string;
+
+    // entityEdit loads the row via the detail QN, edits, then saves via update.
+    const loaded = await stack.http.queryOk<Record<string, unknown>>(
+      "tenant:query:tenant:detail",
+      { id },
+      systemAdmin,
+    );
+    expect(loaded["name"]).toBe("Delta");
+
+    await stack.http.writeOk(
+      "tenant:write:tenant:update",
+      { id, version: loaded["version"], changes: { name: "Delta GmbH" } },
+      systemAdmin,
+    );
+
+    const reloaded = await stack.http.queryOk<Record<string, unknown>>(
+      "tenant:query:tenant:detail",
+      { id },
+      systemAdmin,
+    );
+    expect(reloaded["name"]).toBe("Delta GmbH");
+  });
+
+  test("the convention handlers are SystemAdmin-gated", () => {
+    expect(rolesOf(stack.registry.getQueryHandler("tenant:query:tenant:list")?.access)).toEqual([
+      "SystemAdmin",
+    ]);
+    expect(rolesOf(stack.registry.getQueryHandler("tenant:query:tenant:detail")?.access)).toEqual([
+      "SystemAdmin",
+    ]);
+    expect(rolesOf(stack.registry.getWriteHandler("tenant:write:tenant:update")?.access)).toEqual([
+      "SystemAdmin",
+    ]);
+  });
+});

package/src/tenant/feature.ts

@@ -2,6 +2,9 @@ import {
   access,
   createSystemConfig,
   createTenantConfig,
+  defineEntityDetailHandler,
+  defineEntityListHandler,
+  defineEntityUpdateHandler,
   defineFeature,
   type FeatureDefinition,
 } from "@cosmicdrift/kumiko-framework/engine";
@@ -22,6 +25,7 @@ import { updateMemberRolesWrite } from "./handlers/update-member-roles.write";
 import { tenantInvitationEntity } from "./invitation-table";
 import { tenantMembershipEntity } from "./membership-table";
 import { tenantEntity } from "./schema/tenant";
+import { tenantEditScreen, tenantListScreen } from "./screens";
 
 export { tenantEntity, tenantTable } from "./schema/tenant";
 
@@ -32,6 +36,11 @@ export function createTenantFeature(): FeatureDefinition {
     r.describe(
       "Registers the three core multi-tenancy entities \u2014 `tenant`, `tenant-membership`, and `tenant-invitation` (DB tables `read_tenants`, `read_tenant_memberships`, and `read_tenant_invitations`) \u2014 along with write handlers for create/update/disable/enable/addMember/removeMember/updateMemberRoles and the matching queries. It also declares a set of per-tenant config keys (companyName, timezone, locale, SMTP credentials) and system-only keys (priceModel, maxUsers) via `r.config({ keys: { ... } })`. Use this feature in every multi-tenant app; membership resolution and invitation flows depend on it, and `auth-email-password` requires it.",
     );
+    r.uiHints({
+      displayLabel: "Multi-Tenant Core",
+      category: "identity",
+      recommended: true,
+    });
     r.systemScope();
     r.requires("config");
     r.entity("tenant", tenantEntity);
@@ -108,6 +117,24 @@ export function createTenantFeature(): FeatureDefinition {
       invitations: r.queryHandler(invitationsQuery),
     };
 
+    // Entity-convention handlers for the SystemAdmin entityList/entityEdit
+    // screens. The feature's original handlers predate the `<entity>:<verb>`
+    // naming (they sit on tenant:query:list / tenant:write:update); entityList/
+    // entityEdit resolve tenant:query:tenant:{list,detail} + tenant:write:tenant:
+    // update by convention, so these are added alongside (no rename = no break
+    // for existing callers). Cross-tenant because the feature is systemScope.
+    r.queryHandler(
+      defineEntityListHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+    );
+    r.queryHandler(
+      defineEntityDetailHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+    );
+    r.writeHandler(
+      defineEntityUpdateHandler("tenant", tenantEntity, { access: { roles: ["SystemAdmin"] } }),
+    );
+    r.screen(tenantListScreen);
+    r.screen(tenantEditScreen);
+
     return { handlers, queries };
   });
 }

package/src/tenant/screens.ts

@@ -0,0 +1,46 @@
+import type {
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Cross-tenant SystemAdmin platform view of the tenants themselves. The tenant
+// feature runs with `r.systemScope()`, so the entityList returns every tenant.
+// Both screens are SystemAdmin-gated and inert until an app navs them.
+//
+// Backed by the entity-convention handlers registered in feature.ts
+// (tenant:query:tenant:{list,detail}, tenant:write:tenant:update). The legacy
+// `tenant:query:list` / `tenant:write:update` handlers stay for existing
+// callers — these screens bind to the entity-suffixed QNs by convention.
+
+export const tenantListScreen: EntityListScreenDefinition = {
+  id: "tenant-list",
+  type: "entityList",
+  entity: "tenant",
+  columns: ["key", "name", "isEnabled"],
+  rowActions: [
+    {
+      kind: "navigate",
+      id: "edit",
+      label: "kumiko.actions.edit",
+      screen: "tenant-edit",
+      entityId: "id",
+    },
+  ],
+  searchable: false,
+  access: { roles: ["SystemAdmin"] },
+};
+
+export const tenantEditScreen: EntityEditScreenDefinition = {
+  id: "tenant-edit",
+  type: "entityEdit",
+  entity: "tenant",
+  layout: {
+    // `key` is the unique admin-URL slug — shown in the list, not editable here.
+    sections: [{ columns: 2, fields: ["name", "isEnabled"] }],
+  },
+  // No raw tenant creation (onboarding owns membership/owner setup) and no
+  // hard delete (no tenant:write:tenant:delete — disable via isEnabled instead).
+  allowCreate: false,
+  allowDelete: false,
+  access: { roles: ["SystemAdmin"] },
+};

package/src/user/__tests__/admin-screens.boot.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "@cosmicdrift/kumiko-framework/engine";
+import { createConfigFeature } from "../../config/feature";
+import { createTenantFeature } from "../../tenant/feature";
+import { createUserFeature } from "../feature";
+
+// The SystemAdmin platform screens (entityList + entityEdit for user/tenant)
+// must live IN the user/tenant features — the boot-validator forbids
+// cross-feature screen ownership. The validator checks screen STRUCTURE
+// (entity-local, columns/fields exist, rowAction targets resolve) but NOT that
+// an entityEdit has a matching update/detail handler. That convention-QN wiring
+// is the load-bearing part here, so it is asserted explicitly.
+//
+// QN convention (collectWriteHandlerQns / collectScreenQns): a handler keyed
+// "<short>" in feature "<f>" resolves to "<f>:<kind>:<short>". entityList loads
+// "<f>:query:<entity>:list", entityEdit loads "<f>:query:<entity>:detail" and
+// saves via "<f>:write:<entity>:{create,update}".
+
+describe("user + tenant SystemAdmin admin screens", () => {
+  const features = [createConfigFeature(), createUserFeature(), createTenantFeature()];
+
+  test("the assembled feature set boot-validates", () => {
+    expect(() => validateBoot(features)).not.toThrow();
+  });
+
+  test("user feature ships SystemAdmin-gated list + edit screens", () => {
+    const user = createUserFeature();
+    expect(Object.keys(user.screens)).toEqual(expect.arrayContaining(["user-list", "user-edit"]));
+    const list = user.screens["user-list"];
+    expect(list?.type).toBe("entityList");
+    expect(list?.access).toEqual({ roles: ["SystemAdmin"] });
+    expect(user.screens["user-edit"]?.type).toBe("entityEdit");
+  });
+
+  test("user list/detail/create/update handlers already sit on the screen QNs", () => {
+    const user = createUserFeature();
+    // → user:query:user:list, user:query:user:detail
+    expect(Object.keys(user.queryHandlers)).toEqual(
+      expect.arrayContaining(["user:list", "user:detail"]),
+    );
+    // → user:write:user:update (entityEdit save), user:write:user:create ("+ New")
+    expect(Object.keys(user.writeHandlers)).toEqual(
+      expect.arrayContaining(["user:update", "user:create"]),
+    );
+  });
+
+  test("tenant feature ships list + edit screens (edit-only, no hard delete)", () => {
+    const tenant = createTenantFeature();
+    expect(Object.keys(tenant.screens)).toEqual(
+      expect.arrayContaining(["tenant-list", "tenant-edit"]),
+    );
+    const edit = tenant.screens["tenant-edit"];
+    expect(edit?.type).toBe("entityEdit");
+    if (edit?.type === "entityEdit") {
+      expect(edit.allowCreate).toBe(false);
+      expect(edit.allowDelete).toBe(false);
+    }
+  });
+
+  test("tenant gains entity-convention handlers without dropping the legacy ones", () => {
+    const tenant = createTenantFeature();
+    // New: entityList/entityEdit resolve tenant:query:tenant:{list,detail} +
+    // tenant:write:tenant:update (the legacy handlers are keyed "list"/"update"
+    // → tenant:query:list / tenant:write:update, which the convention misses).
+    expect(Object.keys(tenant.queryHandlers)).toEqual(
+      expect.arrayContaining(["tenant:list", "tenant:detail"]),
+    );
+    expect(Object.keys(tenant.writeHandlers)).toContain("tenant:update");
+    // Legacy handlers stay for existing callers (no rename = no break).
+    expect(Object.keys(tenant.queryHandlers)).toContain("list");
+    expect(Object.keys(tenant.writeHandlers)).toContain("update");
+  });
+});

package/src/user/feature.ts

@@ -6,6 +6,7 @@ import { listQuery } from "./handlers/list.query";
 import { meQuery } from "./handlers/me.query";
 import { updateWrite } from "./handlers/update.write";
 import { userEntity } from "./schema/user";
+import { userEditScreen, userListScreen } from "./screens";
 
 // The user feature holds the cross-tenant user identity. `systemScope()` means
 // queries and writes bypass the tenant filter — a user exists above any tenant.
@@ -15,6 +16,11 @@ export function createUserFeature(): FeatureDefinition {
     r.describe(
       "Manages the cross-tenant user identity: the `read_users` table holds each user's email, `displayName`, global `roles`, `emailVerified` flag, and lifecycle `status` (active / restricted / deletionRequested / deleted). Because users exist above any individual tenant, the feature runs with `r.systemScope()` \u2014 membership and tenant-specific roles live in the `tenant` feature instead. Add this feature whenever your app needs a persistent, tenant-agnostic user record that auth and GDPR pipelines can reference.",
     );
+    r.uiHints({
+      displayLabel: "User Identity",
+      category: "identity",
+      recommended: true,
+    });
     r.systemScope();
     r.entity("user", userEntity);
 
@@ -30,6 +36,13 @@ export function createUserFeature(): FeatureDefinition {
       findForAuth: r.queryHandler(findForAuthQuery),
     };
 
+    // Cross-tenant SystemAdmin platform screens. Inert until an app navs them;
+    // list/detail/create/update handlers above already sit on the QNs that
+    // entityList/entityEdit resolve by convention (user:query:user:{list,detail},
+    // user:write:user:{create,update}).
+    r.screen(userListScreen);
+    r.screen(userEditScreen);
+
     return { handlers, queries };
   });
 }

package/src/user/screens.ts

@@ -0,0 +1,57 @@
+import type {
+  EntityEditScreenDefinition,
+  EntityListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// Cross-tenant platform admin view of the user identity. Because the user
+// feature runs with `r.systemScope()`, the entityList query returns every
+// user across all tenants — the SystemAdmin platform roster. Both screens are
+// SystemAdmin-gated and stay inert until an app navs them (no auto-nav).
+//
+// Field labels come from the renderer's humanizeSlug fallback (no i18n keys
+// registered) — "Display Name", "Email Verified" etc. Apps can override via
+// their own translations under the `user:entity:user:field:*` convention.
+
+export const userListScreen: EntityListScreenDefinition = {
+  id: "user-list",
+  type: "entityList",
+  entity: "user",
+  columns: ["email", "displayName", "status", "emailVerified"],
+  rowActions: [
+    {
+      kind: "navigate",
+      id: "edit",
+      label: "kumiko.actions.edit",
+      screen: "user-edit",
+      entityId: "id",
+    },
+  ],
+  // No SearchAdapter assumption: search is opt-in per app infra, not a
+  // universal default for a bundled screen.
+  searchable: false,
+  access: { roles: ["SystemAdmin"] },
+};
+
+export const userEditScreen: EntityEditScreenDefinition = {
+  id: "user-edit",
+  type: "entityEdit",
+  entity: "user",
+  layout: {
+    sections: [
+      {
+        columns: 2,
+        fields: ["email", "displayName", "locale", "emailVerified"],
+      },
+    ],
+  },
+  // `roles` is deliberately NOT editable here: it is a raw JSON text column
+  // (`["SystemAdmin"]`) — a free-text input would let a typo corrupt the
+  // privilege column on a live platform. Role management needs a dedicated
+  // surface; the list still shows status for triage.
+  //
+  // Create dispatches user:write:user:create (email + displayName required —
+  // both in the form). Delete is suppressed: there is no user:write:user:delete
+  // — user removal is the GDPR status/forget flow, not a hard delete.
+  allowDelete: false,
+  access: { roles: ["SystemAdmin"] },
+};

package/src/user-data-rights/web/__tests__/public-deletion-gate.test.tsx

@@ -0,0 +1,96 @@
+// Gate path-routing: requestPath → request screen, confirmPath → confirm
+// screen, sonst durch zu children. Bewusst SYNCHRON (kein fireEvent/waitFor) —
+// der #457-CI-Flake trifft nur await-Assertions auf dem geteilten happy-dom-
+// document; ein Render + Sync-Assert im selben Tick ist nicht exponiert.
+// Provider-Wrapper lokal (Dependency-Richtung renderer-web → bundled-features
+// verbietet test-utils-Import).
+
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import {
+  createStaticLocaleResolver,
+  DispatcherProvider,
+  kumikoDefaultTranslations,
+  LocaleProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
+import { render, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { defaultTranslations } from "../i18n";
+import { makePublicDeletionGate } from "../public-deletion-gate";
+
+const resolver = createStaticLocaleResolver({ locale: "de" });
+const stubDispatcher = {
+  write: async () => ({ isSuccess: true, data: {} }),
+} as unknown as Dispatcher;
+
+const ROUTES = { requestPath: "/account/delete", confirmPath: "/account/delete/confirm" };
+
+function renderGate(path: string, gate: ReactNode): ReturnType<typeof within> {
+  window.history.replaceState({}, "", path);
+  const { container } = render(
+    <PrimitivesProvider value={defaultPrimitives}>
+      <LocaleProvider
+        resolver={resolver}
+        fallbackBundles={[defaultTranslations, kumikoDefaultTranslations]}
+      >
+        <DispatcherProvider dispatcher={stubDispatcher}>{gate}</DispatcherProvider>
+      </LocaleProvider>
+    </PrimitivesProvider>,
+  );
+  return within(container);
+}
+
+describe("makePublicDeletionGate", () => {
+  test("requestPath → request screen, children short-circuited", () => {
+    const Gate = makePublicDeletionGate(ROUTES);
+    const ui = renderGate(
+      "/account/delete",
+      <Gate>
+        <div data-testid="app">APP</div>
+      </Gate>,
+    );
+    expect(ui.getByText(/beantragen/)).toBeTruthy();
+    expect(ui.queryByTestId("app")).toBeNull();
+  });
+
+  test("confirmPath → confirm screen, children short-circuited", () => {
+    const Gate = makePublicDeletionGate(ROUTES);
+    const ui = renderGate(
+      "/account/delete/confirm",
+      <Gate>
+        <div data-testid="app">APP</div>
+      </Gate>,
+    );
+    expect(ui.getByText(/bestätigen/)).toBeTruthy();
+    expect(ui.queryByTestId("app")).toBeNull();
+  });
+
+  test("other path → children pass through, no deletion screen", () => {
+    const Gate = makePublicDeletionGate(ROUTES);
+    const ui = renderGate(
+      "/dashboard",
+      <Gate>
+        <div data-testid="app">APP</div>
+      </Gate>,
+    );
+    expect(ui.getByTestId("app")).toBeTruthy();
+    expect(ui.queryByText(/beantragen/)).toBeNull();
+  });
+
+  test("custom shell wraps the matched screen", () => {
+    const Gate = makePublicDeletionGate({
+      ...ROUTES,
+      shell: (screen) => <div data-testid="shell">{screen}</div>,
+    });
+    const ui = renderGate(
+      "/account/delete",
+      <Gate>
+        <span>APP</span>
+      </Gate>,
+    );
+    const shell = ui.getByTestId("shell");
+    expect(within(shell).getByText(/beantragen/)).toBeTruthy();
+  });
+});

package/src/user-data-rights/web/client-plugin.tsx

@@ -11,20 +11,28 @@ import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
 import { PRIVACY_CENTER_SCREEN_ID, USER_DATA_RIGHTS_FEATURE } from "../constants";
 import { defaultTranslations } from "./i18n";
 import { PrivacyCenterScreen } from "./privacy-center-screen";
+import { makePublicDeletionGate, type PublicDeletionRoutes } from "./public-deletion-gate";
 
 export type UserDataRightsClientOptions = {
   /** Key-weise Overrides über die Default-Bundles (de/en). */
   readonly translations?: TranslationsByLocale;
+  /** Wenn gesetzt: registriert die anonymen (login-freien) Lösch-Screens als
+   *  Gate auf den angegebenen Pfaden. Weglassen → nur der eingeloggte
+   *  privacy-center-Screen. Den Client VOR dem Auth-Client listen, sonst
+   *  landet der anonyme Besucher auf der Login-Maske. */
+  readonly publicDeletion?: PublicDeletionRoutes;
 };
 
 export function userDataRightsClient(
   options?: UserDataRightsClientOptions,
 ): ClientFeatureDefinition {
-  return {
+  const base: ClientFeatureDefinition = {
     name: USER_DATA_RIGHTS_FEATURE,
     translations: mergeTranslations(defaultTranslations, options?.translations ?? {}),
     components: {
       [PRIVACY_CENTER_SCREEN_ID]: PrivacyCenterScreen,
     },
   };
+  if (options?.publicDeletion === undefined) return base;
+  return { ...base, gates: [makePublicDeletionGate(options.publicDeletion)] };
 }

package/src/user-data-rights/web/index.ts

@@ -10,5 +10,6 @@ export type { ConfirmAccountDeletionScreenProps } from "./confirm-deletion-scree
 export { ConfirmAccountDeletionScreen } from "./confirm-deletion-screen";
 export { defaultTranslations } from "./i18n";
 export { formatDate, PrivacyCenterScreen } from "./privacy-center-screen";
+export { makePublicDeletionGate, type PublicDeletionRoutes } from "./public-deletion-gate";
 export type { RequestAccountDeletionScreenProps } from "./request-deletion-screen";
 export { RequestAccountDeletionScreen } from "./request-deletion-screen";

package/src/user-data-rights/web/public-deletion-gate.tsx

@@ -0,0 +1,42 @@
+// @runtime client
+// Public-Gate für die anonyme Account-Löschung. Matcht window.location.pathname:
+// requestPath → RequestAccountDeletionScreen, confirmPath →
+// ConfirmAccountDeletionScreen, sonst durch zur App. Spiegelt makeAuthGate
+// (auth-email-password) — userDataRightsClient hängt es als Gate ein, die App
+// listet den Client VOR dem Auth-Client, damit ein anonymer Besucher die Lösch-
+// Maske statt der Login-Maske sieht. Path-Match beim Render: Apex-Übergänge
+// (der Verify-Link) sind Full-Page-Loads, kein Client-Router.
+//
+// confirmPath MUSS dem Pfad der server-seitigen deletionVerifyUrl entsprechen —
+// der ConfirmScreen liest das ?token aus eben dieser URL.
+
+import type { ComponentType, ReactNode } from "react";
+import { ConfirmAccountDeletionScreen } from "./confirm-deletion-screen";
+import { RequestAccountDeletionScreen } from "./request-deletion-screen";
+
+export type PublicDeletionRoutes = {
+  /** Login-freie Route für die Email-Antrags-Maske (z.B. "/account/delete"). */
+  readonly requestPath: string;
+  /** Login-freie Route für die Token-Bestätigung; = Pfad der deletionVerifyUrl. */
+  readonly confirmPath: string;
+  /** Chrome um die Screen-Card. Default: vollflächig zentriert (wie der Auth-
+   *  defaultShell). Apps reichen ihre eigene Shell (z.B. Marketing-Header). */
+  readonly shell?: (screen: ReactNode) => ReactNode;
+};
+
+const centeredShell = (screen: ReactNode): ReactNode => (
+  <div className="min-h-screen flex items-center justify-center bg-background px-4">{screen}</div>
+);
+
+export function makePublicDeletionGate(
+  routes: PublicDeletionRoutes,
+): ComponentType<{ children: ReactNode }> {
+  const shell = routes.shell ?? centeredShell;
+  function PublicDeletionGate({ children }: { readonly children: ReactNode }): ReactNode {
+    const path = window.location.pathname;
+    if (path === routes.requestPath) return shell(<RequestAccountDeletionScreen />);
+    if (path === routes.confirmPath) return shell(<ConfirmAccountDeletionScreen />);
+    return <>{children}</>;
+  }
+  return PublicDeletionGate;
+}