@cosmicdrift/kumiko-bundled-features 0.24.1 → 0.25.0

package/src/custom-fields/db/queries/retention.ts

@@ -25,15 +25,29 @@ export async function selectHostRowsWithCustomFields(
   return Array.isArray(rowsResult) ? rowsResult : [];
 }
 
-export async function updateHostRowCustomFields(
+export async function applyRetentionRemovals(
   db: DbRunner,
   tableName: string,
-  customFields: Record<string, unknown>,
+  deleteKeys: readonly string[],
+  anonymizeKeys: readonly string[],
   rowId: string,
 ): Promise<void> {
   const quoted = `"${tableName.replace(/"/g, '""')}"`;
-  await asRawClient(db).unsafe(`UPDATE ${quoted} SET custom_fields = $1::jsonb WHERE id = $2`, [
-    customFields,
-    rowId,
-  ]);
+  // Atomic per-row jsonb edit instead of read-modify-write of the whole
+  // object: delete-keys are dropped (`- $1::text[]`), anonymize-keys are set
+  // to JSON null via a merge patch. Operating on the live row value preserves
+  // a concurrent set-custom-field on any *other* key — no lost update.
+  await asRawClient(db).unsafe(
+    `UPDATE ${quoted} SET custom_fields = CASE
+       WHEN jsonb_typeof(custom_fields) = 'object' THEN
+         (custom_fields - $1::text[])
+         || COALESCE(
+              (SELECT jsonb_object_agg(k, 'null'::jsonb) FROM unnest($2::text[]) AS k),
+              '{}'::jsonb
+            )
+       ELSE custom_fields
+     END
+     WHERE id = $3`,
+    [deleteKeys, anonymizeKeys, rowId],
+  );
 }

package/src/custom-fields/executor.ts

@@ -0,0 +1,10 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { fieldDefinitionEntity } from "./entity";
+
+// Single field-definition executor shared by the four define/delete handlers.
+// createEntityExecutor is side-effect-free; instantiating it once keeps the
+// table+executor pair in one place instead of rebuilding it per handler module.
+export const { executor: fieldDefinitionExecutor } = createEntityExecutor(
+  "field-definition",
+  fieldDefinitionEntity,
+);

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>;
 

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/lib/field-access.ts

@@ -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>,

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/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>

package/src/custom-fields/web/i18n.ts

@@ -0,0 +1,30 @@
+// @runtime client
+// Default translation bundle for the custom-fields UI. customFieldsClient()
+// hangs it into the LocaleProvider as a fallback bundle — apps override
+// individual keys via `customFieldsClient({ translations: { de: { ... } } })`.
+//
+// Keys follow `custom-fields.<area>.<slug>`. `custom-fields.errors.*` mirror
+// the i18nKeys the server-side handlers emit (e.g. `custom-fields:save-failed`).
+
+import type { TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
+
+export const defaultTranslations: TranslationsByLocale = {
+  de: {
+    "custom-fields.form.createMode": "Speichere zuerst den Eintrag, um Custom-Felder zu setzen.",
+    "custom-fields.form.loading": "Lädt…",
+    "custom-fields.form.empty": 'Keine Custom-Felder für "{entityName}" definiert.',
+    "custom-fields.form.save": "Custom-Felder speichern",
+    "custom-fields.form.saving": "Speichert…",
+    "custom-fields.errors.loadFailed": "Custom-Felder konnten nicht geladen werden.",
+    "custom-fields.errors.saveFailed": "Speichern fehlgeschlagen.",
+  },
+  en: {
+    "custom-fields.form.createMode": "Save the entity first to add custom field values.",
+    "custom-fields.form.loading": "Loading…",
+    "custom-fields.form.empty": 'No custom fields defined for "{entityName}".',
+    "custom-fields.form.save": "Save custom fields",
+    "custom-fields.form.saving": "Saving…",
+    "custom-fields.errors.loadFailed": "Could not load custom fields.",
+    "custom-fields.errors.saveFailed": "Save failed.",
+  },
+};

package/src/custom-fields/wire-for-entity.ts

@@ -171,8 +171,8 @@ export function wireCustomFieldsFor<TReg extends FeatureRegistrar<string>>(
       const customFields = row["customFields"];
       if (customFields && typeof customFields === "object" && !Array.isArray(customFields)) {
         return {
-          ...row,
           ...(customFields as Record<string, unknown>), // @cast-boundary db-row jsonb runtime-untyped
+          ...row, // base fields win: a custom fieldKey named `id`/`name` must not shadow the real column
         };
       }
       return row;