@cosmicdrift/kumiko-bundled-features 0.24.0 → 0.25.0

package/src/custom-fields/feature.ts

@@ -37,7 +37,12 @@
 //    Value-Validation gegen serializedField → set-custom-field via fieldToZod —
 //    alle erledigt.)
 
-import { defineEntityListHandler, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  defineEntityListHandler,
+  defineFeature,
+  type FeatureRegistrar,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
 import { z } from "zod";
 import {
   CUSTOM_FIELD_CLEARED_EVENT,
@@ -71,12 +76,14 @@ const fieldDefinitionDeletedSchema = z.object({
   tenantId: z.string().optional(),
 });
 
-// Singleton feature-definition mit typed exports. Handler + wire-for-entity
-// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
-// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
-// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
-// kein top-level-access stattfindet.
-export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) => {
+// Shared registration body for both the singleton and the quota-variant.
+// Only the define-tenant-field handler differs (quota baked in or not); every
+// other entity/event/handler is registered identically here so a new
+// event/handler can never silently miss the quota variant.
+function registerCustomFields(
+  r: FeatureRegistrar<typeof CUSTOM_FIELDS_FEATURE_NAME>,
+  defineTenantHandler: WriteHandlerDef,
+) {
   r.entity("field-definition", fieldDefinitionEntity);
 
   // Event-types — qualified als "custom-fields:event:<short-name>".
@@ -101,7 +108,7 @@ export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r)
   r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
 
   // Definition-CRUD handlers (B1).
-  r.writeHandler(defineTenantFieldHandler);
+  r.writeHandler(defineTenantHandler);
   r.writeHandler(defineSystemFieldHandler);
   r.writeHandler(deleteTenantFieldHandler);
   r.writeHandler(deleteSystemFieldHandler);
@@ -116,7 +123,16 @@ export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r)
   );
 
   return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
-});
+}
+
+// Singleton feature-definition mit typed exports. Handler + wire-for-entity
+// importieren diesen `customFieldsFeature` und greifen lazy in ihrer
+// runtime-arrow-fn auf `.exports.<event>.name` zu — der module-cycle
+// (feature.ts -> handlers/*.write.ts -> feature.ts) löst sich auf weil
+// kein top-level-access stattfindet.
+export const customFieldsFeature = defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+  registerCustomFields(r, defineTenantFieldHandler),
+);
 
 // Backwards-compat-wrapper. Bestehende Caller (z.B. integration-tests,
 // host-apps) nutzen weiterhin `createCustomFieldsFeature()`. Returnt den
@@ -133,34 +149,11 @@ export function createCustomFieldsFeature(
   if (opts.fieldDefinitionLimitPerTenant === undefined) {
     return customFieldsFeature;
   }
-  return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) => {
-    r.entity("field-definition", fieldDefinitionEntity);
-
-    const setEvent = r.defineEvent(CUSTOM_FIELD_SET_EVENT, customFieldSetSchema);
-    const clearedEvent = r.defineEvent(CUSTOM_FIELD_CLEARED_EVENT, customFieldClearedSchema);
-    const fieldDefinitionDeletedEvent = r.defineEvent(
-      FIELD_DEFINITION_DELETED_EVENT,
-      fieldDefinitionDeletedSchema,
-    );
-
-    r.extendsRegistrar(CUSTOM_FIELDS_EXTENSION, {});
-
-    r.writeHandler(
-      createDefineTenantFieldHandler({
-        fieldDefinitionLimitPerTenant: opts.fieldDefinitionLimitPerTenant,
-      }),
-    );
-    r.writeHandler(defineSystemFieldHandler);
-    r.writeHandler(deleteTenantFieldHandler);
-    r.writeHandler(deleteSystemFieldHandler);
-
-    r.writeHandler(setCustomFieldHandler);
-    r.writeHandler(clearCustomFieldHandler);
-
-    r.queryHandler(
-      defineEntityListHandler("field-definition", fieldDefinitionEntity, tenantAdminAccess),
-    );
-
-    return { setEvent, clearedEvent, fieldDefinitionDeletedEvent };
-  });
+  const limit = opts.fieldDefinitionLimitPerTenant;
+  return defineFeature(CUSTOM_FIELDS_FEATURE_NAME, (r) =>
+    registerCustomFields(
+      r,
+      createDefineTenantFieldHandler({ fieldDefinitionLimitPerTenant: limit }),
+    ),
+  );
 }

package/src/custom-fields/handlers/clear-custom-field.write.ts

@@ -7,7 +7,11 @@ import { checkFieldAccessForWrite } from "../lib/field-access";
 export const clearCustomFieldPayloadSchema = z.object({
   entityName: z.string().min(1).max(64),
   entityId: z.string().min(1),
-  fieldKey: z.string().min(1).max(64),
+  fieldKey: z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
 });
 export type ClearCustomFieldPayload = z.infer<typeof clearCustomFieldPayloadSchema>;
 
@@ -36,6 +40,9 @@ export const clearCustomFieldHandler: WriteHandlerDef = {
       if (accessCheck.reason === "field_definition_not_found") {
         return failNotFound("fieldDefinition", payload.fieldKey);
       }
+      if (accessCheck.reason === "field_definition_corrupt") {
+        return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+      }
       return failUnprocessable("field_access_denied", {
         fieldKey: payload.fieldKey,
         requiredRoles: accessCheck.requiredRoles ?? [],

package/src/custom-fields/handlers/define-system-field.write.ts

@@ -1,14 +1,9 @@
-import {
-  createEntityExecutor,
-  SYSTEM_TENANT_ID,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // define-system-field — SystemAdmin definiert eine system-weite Custom-Field-
 // Definition die für ALLE Tenants gilt. tenantId wird auf SYSTEM_TENANT_ID
 // gesetzt (NICHT vom Caller — SystemAdmin's event.user.tenantId würde sonst
@@ -38,20 +33,8 @@ export const defineSystemFieldHandler: WriteHandlerDef = {
     // — the row lives in the system-scope-stream.
     const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
 
-    return executor.create(
-      {
-        id: aggregateId,
-        entityName: payload.entityName,
-        fieldKey: payload.fieldKey,
-        type: payload.serializedField.type,
-        required: payload.required,
-        searchable: payload.searchable,
-        displayOrder: payload.displayOrder,
-        serializedField: JSON.stringify({
-          ...payload.serializedField,
-          label: payload.label,
-        }),
-      },
+    return fieldDefinitionExecutor.create(
+      { id: aggregateId, ...buildFieldDefinitionColumns(payload) },
       systemUser,
       ctx.db,
     );

package/src/custom-fields/handlers/define-tenant-field.write.ts

@@ -1,16 +1,11 @@
-import {
-  createEntityExecutor,
-  isSystemTenant,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
+import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
 import { countTenantFieldDefinitions } from "../lib/quota";
 import { type DefineFieldPayload, defineFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // define-tenant-field — TenantAdmin definiert eine Custom-Field-Definition
 // für seinen eigenen Tenant. tenantId wird automatisch aus event.user.tenantId
 // abgeleitet (NICHT vom Caller setzbar — verhindert Cross-Tenant-Mutation).
@@ -32,8 +27,15 @@ const { executor } = createEntityExecutor("field-definition", fieldDefinitionEnt
 // `unprocessable` + reason `cap_exceeded` BEFORE attempting the insert.
 // The factory below closes over the limit; the legacy const-export keeps
 // behavior unchanged for callers who didn't opt into a limit.
+//
+// Soft cap, not a hard guarantee: the count-then-insert is not serialized, so
+// N concurrent defines with distinct fieldKeys can each read `current < limit`
+// and overshoot by up to N. Acceptable here — defining fields is an admin-only,
+// low-frequency action and the limit is not wired to billing/tier enforcement.
+// If an exact cap is ever needed, serialize via advisory lock or a count
+// constraint at the insert.
 export interface DefineTenantFieldOptions {
-  /** Hard quota — `>= limit` definitions per tenant rejects further defines. */
+  /** Soft cap — `>= limit` definitions per tenant rejects further defines (see header: concurrent defines may overshoot). */
   readonly fieldDefinitionLimitPerTenant?: number;
 }
 
@@ -73,20 +75,8 @@ export function createDefineTenantFieldHandler(
         payload.fieldKey,
       );
 
-      return executor.create(
-        {
-          id: aggregateId,
-          entityName: payload.entityName,
-          fieldKey: payload.fieldKey,
-          type: payload.serializedField.type,
-          required: payload.required,
-          searchable: payload.searchable,
-          displayOrder: payload.displayOrder,
-          serializedField: JSON.stringify({
-            ...payload.serializedField,
-            label: payload.label,
-          }),
-        },
+      return fieldDefinitionExecutor.create(
+        { id: aggregateId, ...buildFieldDefinitionColumns(payload) },
         event.user,
         ctx.db,
       );

package/src/custom-fields/handlers/delete-system-field.write.ts

@@ -1,15 +1,9 @@
-import {
-  createEntityExecutor,
-  SYSTEM_TENANT_ID,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { SYSTEM_TENANT_ID, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
 import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // delete-system-field — SystemAdmin entfernt eine system-weite Field-
 // Definition. Konsequenz: KEIN Tenant kann mehr neue Werte dafür setzen,
 // existing Werte in read_<entity>.customFields jsonb bleiben aber bestehen
@@ -29,7 +23,7 @@ export const deleteSystemFieldHandler: WriteHandlerDef = {
     );
 
     const systemUser = { ...event.user, tenantId: SYSTEM_TENANT_ID };
-    const result = await executor.delete({ id: aggregateId }, systemUser, ctx.db);
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, systemUser, ctx.db);
 
     // Cascade-cleanup-Event — host-entity-MSPs entfernen orphan values aus
     // ihrer customFields jsonb. Im selben TX = atomic.

package/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -1,15 +1,9 @@
-import {
-  createEntityExecutor,
-  isSystemTenant,
-  type WriteHandlerDef,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { fieldDefinitionEntity } from "../entity";
+import { fieldDefinitionExecutor } from "../executor";
 import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 
-const { executor } = createEntityExecutor("field-definition", fieldDefinitionEntity);
-
 // delete-tenant-field — TenantAdmin löscht eigene Field-Definition.
 // Spec-Promise (Plan-Doc v2 "wie Entity-Delete"): Events bleiben im event-
 // store für Audit-Trail. Read-Projection-Row wird entfernt. B2 wird die
@@ -36,7 +30,7 @@ export const deleteTenantFieldHandler: WriteHandlerDef = {
 
     const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
 
-    const result = await executor.delete({ id: aggregateId }, event.user, ctx.db);
+    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
 
     // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
     // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan

package/src/custom-fields/handlers/set-custom-field.write.ts

@@ -13,7 +13,11 @@ export const setCustomFieldPayloadSchema = z.object({
     .min(1)
     .max(64)
     .regex(/^[a-zA-Z][a-zA-Z0-9_-]*$/),
-  value: z.unknown(),
+  // z.unknown() is implicitly optional; reject a missing value here (clearing is
+  // clear-custom-field's job) so the projection never binds JSON.stringify(undefined).
+  value: z
+    .unknown()
+    .refine((v) => v !== undefined, "value is required (use clear-custom-field to remove a value)"),
 });
 export type SetCustomFieldPayload = z.infer<typeof setCustomFieldPayloadSchema>;
 
@@ -57,6 +61,9 @@ export const setCustomFieldHandler: WriteHandlerDef = {
     if (!loaded.found) {
       return failNotFound("fieldDefinition", payload.fieldKey);
     }
+    if (loaded.field === null) {
+      return failUnprocessable("field_definition_corrupt", { fieldKey: payload.fieldKey });
+    }
 
     const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, event.user.roles);
     if (deniedRoles) {

package/src/custom-fields/lib/field-access.ts

@@ -10,15 +10,15 @@ export type FieldAccessCheckResult =
   | { ok: true }
   | {
       ok: false;
-      reason: "field_definition_not_found" | "field_access_denied";
+      reason: "field_definition_not_found" | "field_definition_corrupt" | "field_access_denied";
       requiredRoles?: ReadonlyArray<string>;
     };
 
 export type LoadedFieldDefinition =
   | { found: false }
-  // `field` is null when the row exists but its serialized_field is corrupt —
-  // callers treat that as "no restriction / no schema" (lenient), distinct
-  // from `found: false` (no definition → 404).
+  // `field` is null when the row exists but its serialized_field is corrupt.
+  // A write access-gate treats this fail-closed (secure-by-default): a corrupt
+  // definition must not silently drop a per-field write restriction.
   | { found: true; field: SerializedFieldShape | null };
 
 export async function loadFieldDefinition(
@@ -34,6 +34,10 @@ export async function loadFieldDefinition(
 
 // Pure access-check on an already-loaded definition. Returns the required
 // roles when the caller is denied, or `null` when access is allowed.
+//
+// Contract: `fieldAccess.write` entries MUST be verbatim membership-system role
+// names (e.g. "TenantAdmin", not "Admin") — match is exact like framework-wide
+// `engine/access.ts`; no normalization, so a drifted name denies silently.
 export function fieldWriteAccessDeniedRoles(
   field: SerializedFieldShape | null,
   userRoles: ReadonlyArray<string>,
@@ -54,6 +58,7 @@ export async function checkFieldAccessForWrite(
 ): Promise<FieldAccessCheckResult> {
   const loaded = await loadFieldDefinition(db, tenantId, entityName, fieldKey);
   if (!loaded.found) return { ok: false, reason: "field_definition_not_found" };
+  if (loaded.field === null) return { ok: false, reason: "field_definition_corrupt" };
 
   const deniedRoles = fieldWriteAccessDeniedRoles(loaded.field, userRoles);
   if (!deniedRoles) return { ok: true };

package/src/custom-fields/lib/field-definition-row.ts

@@ -0,0 +1,33 @@
+import type { DefineFieldPayload } from "../schemas";
+
+export interface FieldDefinitionColumns {
+  readonly entityName: string;
+  readonly fieldKey: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly searchable: boolean;
+  readonly displayOrder: number;
+  readonly serializedField: string;
+}
+
+// The required/searchable/displayOrder columns are a denormalized projection of
+// serializedField — derive, don't default. Zod gives top-level `required` a
+// `.default(false)`, so "caller omitted it" is indistinguishable from `false`
+// post-parse; serializedField-present therefore wins to preserve caller intent.
+export function buildFieldDefinitionColumns(payload: DefineFieldPayload): FieldDefinitionColumns {
+  const sf = payload.serializedField;
+  const required = typeof sf["required"] === "boolean" ? sf["required"] : payload.required;
+  const searchable = typeof sf["searchable"] === "boolean" ? sf["searchable"] : payload.searchable;
+  const displayOrder =
+    typeof sf["displayOrder"] === "number" ? sf["displayOrder"] : payload.displayOrder;
+
+  return {
+    entityName: payload.entityName,
+    fieldKey: payload.fieldKey,
+    type: sf.type,
+    required,
+    searchable,
+    displayOrder,
+    serializedField: JSON.stringify({ ...sf, label: payload.label }),
+  };
+}

package/src/custom-fields/lib/value-schema.ts

@@ -47,20 +47,32 @@ export function buildCustomFieldValueSchema(parsedField: unknown): z.ZodTypeAny
   // Embedded sub-fields: pre-check the sub-type set so we surface unknown
   // sub-types as "skip validation" (return null) rather than letting
   // fieldToZod's assertUnreachable throw and the catch swallow real bugs.
+  // Build a constraint-stripped copy of each sub-field in the same pass —
+  // symmetric with the top-level strip below. Without it a sub-field's
+  // `required` folds into z.string().min(1) + non-optional, re-enforcing a
+  // constraint the contract ("type-mismatches and ONLY type-mismatches")
+  // drops everywhere else.
+  let strippedSubSchema: Record<string, Record<string, unknown>> | undefined;
   if (rawType === "embedded") {
     const schema = obj["schema"];
     if (!schema || typeof schema !== "object") return null;
-    for (const sub of Object.values(schema)) {
+    strippedSubSchema = {};
+    for (const [subKey, sub] of Object.entries(schema)) {
       if (!sub || typeof sub !== "object") return null;
-      const subType = (sub as Record<string, unknown>)["type"];
+      const subObj = sub as Record<string, unknown>;
+      const subType = subObj["type"];
       if (typeof subType !== "string" || !SUPPORTED_EMBEDDED_SUB_TYPES.has(subType)) {
         return null;
       }
+      const strippedSub = { ...subObj };
+      for (const k of CONSTRAINT_KEYS) delete strippedSub[k];
+      strippedSubSchema[subKey] = strippedSub;
     }
   }
 
   const fieldDef: Record<string, unknown> = { ...obj };
   for (const k of CONSTRAINT_KEYS) delete fieldDef[k];
+  if (strippedSubSchema !== undefined) fieldDef["schema"] = strippedSubSchema;
   if (rawType === "enum") {
     fieldDef["type"] = "select";
     fieldDef["options"] = obj["values"] ?? obj["options"] ?? [];

package/src/custom-fields/run-retention.ts

@@ -18,9 +18,9 @@
 import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
 import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
 import {
+  applyRetentionRemovals,
   selectFieldDefinitionsWithSerialized,
   selectHostRowsWithCustomFields,
-  updateHostRowCustomFields,
 } from "./db/queries/retention";
 import { parseSerializedField } from "./lib/parse-serialized-field";
 
@@ -122,17 +122,18 @@ export async function runCustomFieldsRetention(
     // skip: nothing on this row aged out — no UPDATE needed.
     if (removals.length === 0) continue;
 
-    const mutated: Record<string, unknown> = { ...row.customFields };
+    const deleteKeys: string[] = [];
+    const anonymizeKeys: string[] = [];
     for (const { key, strategy } of removals) {
       if (strategy === "delete") {
-        delete mutated[key];
+        deleteKeys.push(key);
       } else {
-        mutated[key] = null;
+        anonymizeKeys.push(key);
       }
       removalsByFieldKey[key] = (removalsByFieldKey[key] ?? 0) + 1;
     }
 
-    await updateHostRowCustomFields(opts.db, tableName, mutated, row.id);
+    await applyRetentionRemovals(opts.db, tableName, deleteKeys, anonymizeKeys, row.id);
     rowsUpdated++;
   }
 

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

@@ -8,6 +8,7 @@ import { defaultPrimitives } from "@cosmicdrift/kumiko-renderer-web";
 import { fireEvent, render, screen } from "@testing-library/react";
 import type { ReactNode } from "react";
 import { CustomFieldsFormSection } from "../custom-fields-form-section";
+import { defaultTranslations } from "../i18n";
 
 type FieldRow = {
   id: string;
@@ -21,6 +22,13 @@ type FieldRow = {
 const dispatchSpy = mock(async () => ({ isSuccess: true, data: undefined }));
 let mockedQueryRows: readonly FieldRow[] = [];
 
+const useQuerySpy = mock((_type: string, _params: unknown, _options?: { enabled?: boolean }) => ({
+  data: { rows: mockedQueryRows },
+  loading: false,
+  error: null,
+  refetch: mock(),
+}));
+
 const actual_renderer = await import("@cosmicdrift/kumiko-renderer");
 mock.module("@cosmicdrift/kumiko-renderer", () => ({
   ...actual_renderer,
@@ -29,17 +37,12 @@ mock.module("@cosmicdrift/kumiko-renderer", () => ({
     query: mock(),
     batch: mock(),
   })),
-  useQuery: mock(() => ({
-    data: { rows: mockedQueryRows },
-    loading: false,
-    error: null,
-    refetch: mock(),
-  })),
+  useQuery: useQuerySpy,
 }));
 
 function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
   return (
-    <LocaleProvider resolver={createStaticLocaleResolver()}>
+    <LocaleProvider resolver={createStaticLocaleResolver()} fallbackBundles={[defaultTranslations]}>
       <PrimitivesProvider value={defaultPrimitives}>{children}</PrimitivesProvider>
     </LocaleProvider>
   );
@@ -107,8 +110,9 @@ describe("CustomFieldsFormSection", () => {
     });
   });
 
-  test("shows create-mode banner when entityId is null", () => {
+  test("shows create-mode banner when entityId is null and skips the fieldDefinition query", () => {
     mockedQueryRows = [];
+    useQuerySpy.mockClear();
 
     render(
       <Wrapper>
@@ -116,8 +120,14 @@ describe("CustomFieldsFormSection", () => {
       </Wrapper>,
     );
 
-    expect(screen.getByTestId("custom-fields-form-create-mode")).toBeTruthy();
+    const banner = screen.getByTestId("custom-fields-form-create-mode");
+    expect(banner).toBeTruthy();
     expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+    // The banner shows the translated string, not the raw i18n key.
+    expect(banner.textContent).toBe("Save the entity first to add custom field values.");
+    // create-mode discards the query result via the early return, so the
+    // fetch-on-mount must be disabled — no wasted server roundtrip.
+    expect(useQuerySpy.mock.calls[0]?.[2]).toEqual({ enabled: false });
   });
 
   test("shows empty banner when no fieldDefinitions match entityName", () => {
@@ -138,7 +148,32 @@ describe("CustomFieldsFormSection", () => {
       </Wrapper>,
     );
 
-    expect(screen.getByTestId("custom-fields-form-empty")).toBeTruthy();
+    const banner = screen.getByTestId("custom-fields-form-empty");
+    expect(banner).toBeTruthy();
     expect(screen.queryByTestId("custom-fields-form-section")).toBeNull();
+    // Translated + interpolated with the host entity name, not the raw key.
+    expect(banner.textContent).toBe('No custom fields defined for "component".');
+  });
+
+  test("save button renders the translated label, not the raw i18n key", () => {
+    mockedQueryRows = [
+      {
+        id: "f1",
+        entityName: "component",
+        fieldKey: "vendor",
+        type: "text",
+        required: false,
+        displayOrder: 1,
+      },
+    ];
+
+    render(
+      <Wrapper>
+        <CustomFieldsFormSection entityName="component" entityId="row-42" />
+      </Wrapper>,
+    );
+
+    const saveBtn = screen.getByTestId("custom-fields-form-save");
+    expect(saveBtn.textContent).toBe("Save custom fields");
   });
 });

package/src/custom-fields/web/client-plugin.tsx

@@ -14,6 +14,7 @@
 import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
 import { CUSTOM_FIELDS_FEATURE_NAME, CUSTOM_FIELDS_FORM_EXTENSION_NAME } from "../constants";
 import { CustomFieldsFormSection } from "./custom-fields-form-section";
+import { defaultTranslations } from "./i18n";
 
 export function customFieldsClient(): ClientFeatureDefinition {
   return {
@@ -21,5 +22,6 @@ export function customFieldsClient(): ClientFeatureDefinition {
     extensionSectionComponents: {
       [CUSTOM_FIELDS_FORM_EXTENSION_NAME]: CustomFieldsFormSection,
     },
+    translations: defaultTranslations,
   };
 }

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

@@ -10,7 +10,12 @@
 // `component: { react: { __component: CUSTOM_FIELDS_FORM_EXTENSION_NAME } }`
 // referenziert.
 
-import { useDispatcher, usePrimitives, useQuery } from "@cosmicdrift/kumiko-renderer";
+import {
+  useDispatcher,
+  usePrimitives,
+  useQuery,
+  useTranslation,
+} from "@cosmicdrift/kumiko-renderer";
 import { type ReactNode, useState } from "react";
 import { CustomFieldsHandlers, CustomFieldsQueries } from "../constants";
 
@@ -35,8 +40,13 @@ export function CustomFieldsFormSection({
   readonly entityId: string | null;
 }): ReactNode {
   const { Banner, Button, Field, Input, Text } = usePrimitives();
+  const t = useTranslation();
   const dispatcher = useDispatcher();
-  const query = useQuery<FieldDefinitionListResponse>(CustomFieldsQueries.fieldDefinitionList, {});
+  const query = useQuery<FieldDefinitionListResponse>(
+    CustomFieldsQueries.fieldDefinitionList,
+    {},
+    { enabled: entityId !== null },
+  );
   const [pending, setPending] = useState<Readonly<Record<string, string>>>({});
   const [saving, setSaving] = useState(false);
   const [errorKey, setErrorKey] = useState<string | null>(null);
@@ -44,21 +54,21 @@ export function CustomFieldsFormSection({
   if (entityId === null) {
     return (
       <Banner variant="info" testId="custom-fields-form-create-mode">
-        <Text>Save the entity first to add custom field values.</Text>
+        <Text>{t("custom-fields.form.createMode")}</Text>
       </Banner>
     );
   }
   if (query.loading && query.data === null) {
     return (
       <Banner variant="loading" testId="custom-fields-form-loading">
-        <Text>Loading…</Text>
+        <Text>{t("custom-fields.form.loading")}</Text>
       </Banner>
     );
   }
   if (query.error) {
     return (
       <Banner variant="error" testId="custom-fields-form-error">
-        <Text>{query.error.i18nKey}</Text>
+        <Text>{t(query.error.i18nKey, query.error.i18nParams)}</Text>
       </Banner>
     );
   }
@@ -71,7 +81,7 @@ export function CustomFieldsFormSection({
   if (matchingFields.length === 0) {
     return (
       <Banner variant="info" testId="custom-fields-form-empty">
-        <Text>No custom fields defined for "{entityName}".</Text>
+        <Text>{t("custom-fields.form.empty", { entityName })}</Text>
       </Banner>
     );
   }
@@ -91,7 +101,7 @@ export function CustomFieldsFormSection({
           value,
         });
         if (!result.isSuccess) {
-          setErrorKey(result.error?.i18nKey ?? "custom-fields:save-failed");
+          setErrorKey(result.error?.i18nKey ?? "custom-fields.errors.saveFailed");
           return;
         }
       }
@@ -123,11 +133,11 @@ export function CustomFieldsFormSection({
         disabled={saving || !dirty}
         testId="custom-fields-form-save"
       >
-        {saving ? "Saving…" : "Save custom fields"}
+        {saving ? t("custom-fields.form.saving") : t("custom-fields.form.save")}
       </Button>
       {errorKey !== null && (
         <Banner variant="error" testId="custom-fields-form-save-error">
-          <Text>{errorKey}</Text>
+          <Text>{t(errorKey)}</Text>
         </Banner>
       )}
     </div>