@cosmicdrift/kumiko-renderer 0.1.0

package/src/context/dispatcher-context.tsx

@@ -0,0 +1,59 @@
+import type { Dispatcher, DispatcherStatus } from "@cosmicdrift/kumiko-headless";
+import { createContext, type ReactNode, useContext } from "react";
+import { useStore } from "../hooks/use-store";
+
+// React Context threading the Dispatcher through the tree. An app
+// wraps its root in <DispatcherProvider dispatcher={createLiveDispatcher()}>
+// and every hook below reaches into that context instead of taking the
+// dispatcher as a prop on every call site. Same pattern most routers
+// and query-libraries use; nothing novel, but worth spelling out once.
+//
+// The context holds the Dispatcher INSTANCE, not a factory — a single
+// dispatcher per app (rebuilding would wipe its in-flight tracking and
+// status listeners). Tests wire a fake dispatcher in directly.
+
+const DispatcherContext = createContext<Dispatcher | null>(null);
+
+export type DispatcherProviderProps = {
+  readonly dispatcher: Dispatcher;
+  readonly children: ReactNode;
+};
+
+export function DispatcherProvider({ dispatcher, children }: DispatcherProviderProps): ReactNode {
+  return <DispatcherContext value={dispatcher}>{children}</DispatcherContext>;
+}
+
+// Reads the ambient Dispatcher. Throws instead of returning null when
+// no provider is mounted — a dispatcher-less hook is always a
+// developer error (the app forgot to wrap its root) and surfacing it
+// early beats debugging "why did my write silently do nothing" later.
+export function useDispatcher(): Dispatcher {
+  const dispatcher = useContext(DispatcherContext);
+  if (!dispatcher) {
+    throw new Error(
+      "useDispatcher: no <DispatcherProvider> mounted above this component. Wrap your app root with <DispatcherProvider dispatcher={createLiveDispatcher()}>.",
+    );
+  }
+  return dispatcher;
+}
+
+// Soft-Variante: null wenn kein Provider mounted statt throw. Für
+// Components die einen Dispatcher OPTIONAL brauchen (z.B. KumikoScreen
+// rendert mit/ohne rowActions; die Test-Suite mountet kein Dispatcher
+// wenn der Screen keine Mutation triggert). Caller ist zuständig dass
+// er bei null einen sinnvollen Fallback hat (typisch: kein Action-Wiring).
+export function useOptionalDispatcher(): Dispatcher | undefined {
+  return useContext(DispatcherContext) ?? undefined;
+}
+
+// Subscribes to online/offline/syncing transitions. The dispatcher
+// exposes `statusStore: Store<DispatcherStatus>` directly; useStore is
+// the canonical React-binding for that contract.
+//
+// Server rendering: useStore reads the store's getServerSnapshot which
+// returns the same snapshot the client sees on hydration — for the
+// live-dispatcher that's "online" (the optimistic boot default), so
+// no flash on hydration.
+export function useDispatcherStatus(): DispatcherStatus {
+  return useStore(useDispatcher().statusStore);
+}

package/src/hooks/reference-limits.ts

@@ -0,0 +1,18 @@
+// Tier 2.7e Audit-Fix #7: Reference-Lookup-Limits zentral.
+//
+// Zwei verschiedene Use-Cases mit unterschiedlichen Default-Limits:
+//   - Combobox-Edit (single User picks one): 50 reicht weil
+//     typed-search-Fallback aktiv ist (REMOTE_SEARCH_DEBOUNCE_MS).
+//   - List-Bulk-Display (Cell-Render für viele Rows): 200 weil wir
+//     pro Reference-Spalte einmal pro Page laden, nicht pro Cell.
+//
+// Apps können die Defaults überschreiben indem sie die Konstanten
+// hier neu setzen — pro feature/app gibt's heute keine Override-API
+// (das wäre eine Erweiterung in createKumikoApp, separater Sprint).
+// Die Konstanten leben in einem eigenen Modul damit Future-Author
+// sie an einer Stelle findet statt verstreut zwischen render-field
+// und use-reference-lookup.
+
+export const REFERENCE_COMBOBOX_LIMIT = 50;
+export const REFERENCE_LIST_LOOKUP_LIMIT = 200;
+export const REFERENCE_SEARCH_DEBOUNCE_MS = 300;

package/src/hooks/use-form.ts

@@ -0,0 +1,88 @@
+import type {
+  FormController,
+  FormControllerOptions,
+  FormSnapshot,
+  FormValues,
+} from "@cosmicdrift/kumiko-headless";
+import { createFormController } from "@cosmicdrift/kumiko-headless";
+import { useMemo, useSyncExternalStore } from "react";
+import { useDispatcher } from "../context/dispatcher-context";
+
+// Thin React wrapper around createFormController. Returns both the
+// controller (imperative — setField, submit, reset) and the current
+// snapshot (reactive — values, errors, isDirty). React subscribes via
+// useSyncExternalStore so re-renders happen exactly when the snapshot
+// reference changes, which the controller guarantees.
+//
+// The `submit.dispatcher` config is filled from context if omitted,
+// so the typical call site is just:
+//   const { snapshot, controller } = useForm({
+//     initial: { ... },
+//     schema,
+//     submit: { type: "foo:create" },
+//   });
+// and the hook wires the ambient DispatcherProvider's dispatcher in.
+
+export type UseFormOptions<TValues extends FormValues, TCtx = unknown> = Omit<
+  FormControllerOptions<TValues, TCtx>,
+  "submit"
+> & {
+  // `submit` here takes everything the ui-core SubmitConfig takes
+  // EXCEPT dispatcher — that comes from context. Passing an explicit
+  // dispatcher here (e.g. from a test) overrides the context one.
+  readonly submit?: Omit<
+    NonNullable<FormControllerOptions<TValues, TCtx>["submit"]>,
+    "dispatcher"
+  > & {
+    readonly dispatcher?: NonNullable<FormControllerOptions<TValues, TCtx>["submit"]>["dispatcher"];
+  };
+};
+
+export type UseFormResult<TValues extends FormValues> = {
+  readonly controller: FormController<TValues>;
+  readonly snapshot: FormSnapshot<TValues>;
+};
+
+export function useForm<TValues extends FormValues, TCtx = unknown>(
+  options: UseFormOptions<TValues, TCtx>,
+): UseFormResult<TValues> {
+  const contextDispatcher = useDispatcher();
+
+  // The controller is created once per mount. `options` mutates across
+  // renders in normal React usage (closures get new references), but
+  // the controller's behaviour depends only on the initial shape — we
+  // deliberately don't re-create on option-identity change, which
+  // would wipe in-flight state and "forget" dirty edits on every
+  // parent re-render. If the app needs a reset, call controller.reset()
+  // or re-mount the form (key prop).
+  // Controller lifetime = hook lifetime. Options deliberately NOT in
+  // the deps array; re-creating on option-identity change would wipe
+  // in-flight state and dirty edits on every parent re-render.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: intentional — controller is lifetime-scoped, not render-scoped
+  const controller = useMemo<FormController<TValues>>(() => {
+    // Default the dispatcher to the ambient one, then hand ui-core
+    // a fully-populated SubmitConfig. The input signature lets the
+    // caller omit `dispatcher`; the output shape createFormController
+    // expects requires it.
+    type FullOptions = FormControllerOptions<TValues, TCtx>;
+    const rawSubmit = options.submit;
+    const submitConfig: FullOptions["submit"] = rawSubmit
+      ? { ...rawSubmit, dispatcher: rawSubmit.dispatcher ?? contextDispatcher }
+      : undefined;
+    const controllerOptions: FullOptions = {
+      ...(options as FullOptions),
+      ...(submitConfig !== undefined && { submit: submitConfig }),
+    };
+    return createFormController<TValues, TCtx>(controllerOptions);
+  }, []);
+
+  const snapshot = useSyncExternalStore(
+    (notify) => controller.subscribe(notify),
+    () => controller.getSnapshot(),
+    // SSR snapshot: same as getSnapshot(). The controller's initial
+    // snapshot is deterministic from options.initial, safe for server.
+    () => controller.getSnapshot(),
+  );
+
+  return { controller, snapshot };
+}

package/src/hooks/use-list-url-state.ts

@@ -0,0 +1,113 @@
+// useListUrlState — bündelt sort/dir/page/q einer entityList in einen
+// per-screen-id namespaced URL-State. Mit Screen-ID-Prefix damit zwei
+// Listen auf derselben Route (z.B. Dashboard mit Orders + Incidents)
+// nicht über dieselben Query-Keys streiten.
+//
+// Param-Schema pro Liste:
+//   <screenId>.sort  — field name (string)
+//   <screenId>.dir   — "asc" | "desc"
+//   <screenId>.q     — search term (URL-encoded)
+//   <screenId>.page  — 1-based page number (nur bei pagination="pages")
+//
+// Schreibt mit setSearchParams (replaceState — kein push), damit
+// Sort/Filter-Toggles nicht die Browser-History fluten.
+
+import { useCallback, useMemo } from "react";
+import { useNav } from "../app/nav";
+import type { DataTableSort, DataTableSortDir } from "../primitives";
+
+// ListSort + DataTableSort hatten dieselbe Shape und drohten zu driften
+// — aliased auf den primitives-Type (eine Quelle, kein Cast in RenderList).
+export type ListSortDir = DataTableSortDir;
+export type ListSort = DataTableSort;
+
+export type ListUrlState = {
+  /** Aktive Sortierung (oder null = unsorted, Server liefert Default-Order). */
+  readonly sort: ListSort | null;
+  /** Search-Term (leer wenn nicht gesetzt). */
+  readonly q: string;
+  /** 1-basierte Page-Nummer. Bei pagination="infinite" oder false ist
+   *  der Wert ignoriert; Caller liest ihn nur wenn relevant. */
+  readonly page: number;
+};
+
+export type ListUrlStateApi = ListUrlState & {
+  /** Setzt sort + dir atomar. null = unsorted (löscht beide Keys). */
+  readonly setSort: (next: ListSort | null) => void;
+  /** Setzt den Search-Term. Empty-String löscht den Key. Caller debounced
+   *  selber (z.B. useDebouncedCallback in der Search-Input-Komponente). */
+  readonly setQ: (next: string) => void;
+  /** Setzt die Page. 1 oder kleiner löscht den Key (Default-Page). */
+  readonly setPage: (next: number) => void;
+};
+
+// `.` als Trenner: lesbar (`?orders.sort=name`), kollidiert nicht mit
+// üblichen Field-Namen (kebab- oder camelCase ohne Punkt). Boot-Validator
+// pinnt screen.id ohne Punkt — siehe boot-validator entityList Section.
+function key(screenId: string, suffix: string): string {
+  return `${screenId}.${suffix}`;
+}
+
+function parseDir(value: string | undefined): ListSortDir | undefined {
+  return value === "asc" || value === "desc" ? value : undefined;
+}
+
+function parsePage(value: string | undefined): number {
+  if (value === undefined) return 1;
+  const n = Number.parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : 1;
+}
+
+export function useListUrlState(screenId: string): ListUrlStateApi {
+  const nav = useNav();
+  const params = nav.searchParams;
+
+  const sort = useMemo<ListSort | null>(() => {
+    const field = params[key(screenId, "sort")];
+    const dir = parseDir(params[key(screenId, "dir")]);
+    if (field === undefined || field === "" || dir === undefined) return null;
+    return { field, dir };
+  }, [params, screenId]);
+
+  const q = params[key(screenId, "q")] ?? "";
+  const page = parsePage(params[key(screenId, "page")]);
+
+  const setSort = useCallback(
+    (next: ListSort | null) => {
+      // Atomares Update: bei jedem Sort-Wechsel resetten wir auch die
+      // Page (sonst wäre der User auf "Seite 5 von alter Sortierung"
+      // hängen, was visuell verwirrend ist). Page-Reset gilt auch bei
+      // null — gleiche Logik.
+      nav.setSearchParams({
+        [key(screenId, "sort")]: next === null ? null : next.field,
+        [key(screenId, "dir")]: next === null ? null : next.dir,
+        [key(screenId, "page")]: null,
+      });
+    },
+    [nav, screenId],
+  );
+
+  const setQ = useCallback(
+    (next: string) => {
+      // Search-Change resettet Page (gleicher Grund wie Sort) UND
+      // Sort? Nein — User kann mit aktivem Sort suchen wollen, das
+      // soll die Sortierung nicht zerlegen. Nur Page wird gereset.
+      nav.setSearchParams({
+        [key(screenId, "q")]: next === "" ? null : next,
+        [key(screenId, "page")]: null,
+      });
+    },
+    [nav, screenId],
+  );
+
+  const setPage = useCallback(
+    (next: number) => {
+      nav.setSearchParams({
+        [key(screenId, "page")]: next <= 1 ? null : String(next),
+      });
+    },
+    [nav, screenId],
+  );
+
+  return { sort, q, page, setSort, setQ, setPage };
+}

package/src/hooks/use-query.ts

@@ -0,0 +1,129 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context";
+import { useLiveEvents } from "../sse/live-events";
+
+// React wrapper around dispatcher.query. Fires on mount, re-fires
+// whenever `type` or the serialized payload change, and exposes a
+// `refetch` imperative hook for after-mutation reloads.
+//
+// Cancellation: each fetch owns an AbortController; a newer fetch
+// (change in deps or manual refetch) aborts the older one's network
+// call before firing, so a slow request can't overwrite a fresh one.
+// Unmount aborts any in-flight call too — React will throw the
+// "state on unmounted" warning if we set state after unmount, and
+// aborting pre-emptively makes that path a no-op.
+//
+// Result shape modeled on the dispatcher's own QueryResult: a
+// discriminated state so callers can branch on `loading | data | error`
+// without undefined-juggling. The first render is `loading: true,
+// data: null, error: null` (no optimistic "online" cache — add that
+// later if needed).
+
+export type UseQueryResult<TData> = {
+  readonly data: TData | null;
+  readonly error: DispatcherError | null;
+  readonly loading: boolean;
+  readonly refetch: () => Promise<void>;
+};
+
+export type UseQueryOptions = {
+  // When false, skips the automatic fetch-on-mount and re-fetch on
+  // dep-change. Useful for lazy queries that only run after a user
+  // action. `refetch()` still works as an imperative trigger.
+  readonly enabled?: boolean;
+  // When true, subscribe to SSE events for the entity this query
+  // targets and refetch on any create/update/delete/restore event.
+  // The entity-name is parsed from the query type using Kumiko's
+  // `<feature>:query:<entity>:<verb>` convention — if the type
+  // doesn't follow that shape, live-mode is a no-op.
+  readonly live?: boolean;
+};
+
+// Extract the entity-name from a standard Kumiko query type. Returns
+// undefined for non-conforming types so the live-mode silently skips
+// them instead of subscribing to a channel no event will ever match.
+function entityFromQueryType(type: string): string | undefined {
+  // Expected shape: "<feature>:query:<entity>:<verb>"
+  const parts = type.split(":");
+  if (parts.length !== 4) return undefined;
+  if (parts[1] !== "query") return undefined;
+  return parts[2];
+}
+
+export function useQuery<TData = unknown>(
+  type: string,
+  payload: unknown,
+  options: UseQueryOptions = {},
+): UseQueryResult<TData> {
+  const dispatcher = useDispatcher();
+  const { enabled = true, live = false } = options;
+
+  const [data, setData] = useState<TData | null>(null);
+  const [error, setError] = useState<DispatcherError | null>(null);
+  const [loading, setLoading] = useState<boolean>(enabled);
+
+  // Track the AbortController for the most recent fetch so a newer
+  // call can cancel the older one. Ref, not state, because the
+  // controller identity shouldn't trigger a re-render.
+  const activeCtrl = useRef<AbortController | null>(null);
+
+  // Serialize payload so object-identity-changes across renders (the
+  // caller building a fresh `{}` every render) don't loop. Strings are
+  // stable by reference in React's dep-array check.
+  const payloadKey = JSON.stringify(payload);
+
+  // `dispatcher` is stable (context identity); `type` + `payloadKey`
+  // are the meaningful re-run triggers. `payload` itself is intentionally
+  // not in deps — it's serialized into payloadKey above.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: payload goes through payloadKey
+  const run = useCallback(async (): Promise<void> => {
+    // Abort whatever's in flight. observer on Safari 17+ handles this
+    // without raising a fetch-throw in the previous caller — they
+    // already set the error path.
+    activeCtrl.current?.abort();
+    const ctrl = new AbortController();
+    activeCtrl.current = ctrl;
+
+    setLoading(true);
+    const result = await dispatcher.query<TData>(type, payload, { signal: ctrl.signal });
+    // Don't update state if a newer fetch has already taken over.
+    if (ctrl.signal.aborted) return;
+    if (result.isSuccess) {
+      setData(result.data);
+      setError(null);
+    } else {
+      // A cancelled request comes back with code "aborted" from the
+      // dispatcher — skip the state update, another run replaces it.
+      if (result.error.code === "aborted") return;
+      setError(result.error);
+    }
+    setLoading(false);
+  }, [dispatcher, type, payloadKey]);
+
+  useEffect(() => {
+    if (!enabled) {
+      setLoading(false);
+      return;
+    }
+    void run();
+    return () => {
+      activeCtrl.current?.abort();
+    };
+  }, [enabled, run]);
+
+  // Live-mode: auf SSE-Events für die Query-Entity hören und refetchen.
+  // Separater Effect, damit eine Änderung an `live` oder `type` das
+  // Subscription-Lifecycle genau einmal durchwalzt.
+  const subscribeLive = useLiveEvents();
+  useEffect(() => {
+    if (!live || !enabled) return;
+    const entity = entityFromQueryType(type);
+    if (entity === undefined) return;
+    return subscribeLive(entity, () => {
+      void run();
+    });
+  }, [live, enabled, type, run, subscribeLive]);
+
+  return { data, error, loading, refetch: run };
+}

package/src/hooks/use-reference-lookup.ts

@@ -0,0 +1,54 @@
+// Tier 2.7e-4: Renderer-Side Eagerload für Reference-Felder.
+//
+// Pro Reference-Spalte einer Liste wird einmal `<feature>:query:
+// <refEntity>:list` (limit:200) gerufen, eine Map<uuid, displayValue>
+// gebaut, und der Renderer nutzt sie als Cell-Display-Renderer.
+//
+// Strategy-Trade-offs:
+//   - Server-side Drizzle-Joins wären effizienter (eine Query statt
+//     N+1), würden aber die executor-API um lookupTables erweitern
+//     müssen. Für das MVP geht der Renderer-Side-Pfad vor.
+//   - Limit:200 ist eine harte UX-Grenze: bei mehr Entries in der
+//     referenced Entity zeigen die letzten Rows nur noch UUIDs.
+//     Searchable-Combobox (Tier 2.1c) + Server-Eagerload mit
+//     ID-Whitelist heben das später auf.
+//
+// Dieser Hook ist call-stable: Lookup-Map wird durch useQuery's
+// internen Cache shared zwischen List + Edit-Form für die gleiche
+// Entity, Live-Updates kommen via SSE (use-query-live).
+
+import { useMemo } from "react";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "./reference-limits";
+import { useQuery } from "./use-query";
+
+export type ReferenceLookupMap = ReadonlyMap<string, string>;
+
+/** Bulk-Lookup für eine einzelne Reference-Spalte. Liefert eine Map
+ *  von UUID → Display-Value (aus labelField). Während die Query lädt,
+ *  ist die Map leer; der Caller fällt dann auf den UUID-Fallback.
+ *
+ *  `featureName` ist hier das **target**-Feature (refFeature aus
+ *  ViewModel), nicht das current Feature — Cross-Feature-Refs lookup
+ *  laufen damit gegen `<refFeature>:query:<refEntity>:list`. */
+export function useReferenceLookup(
+  featureName: string,
+  refEntity: string,
+  labelField: string,
+): { readonly map: ReferenceLookupMap; readonly loading: boolean } {
+  const queryQn = `${featureName}:query:${refEntity}:list`;
+  const result = useQuery<{ rows: ReadonlyArray<Record<string, unknown>> }>(queryQn, {
+    limit: REFERENCE_LIST_LOOKUP_LIMIT,
+  });
+  const map = useMemo(() => {
+    const out = new Map<string, string>();
+    for (const row of result.data?.rows ?? []) {
+      const id = row["id"];
+      if (id === undefined || id === null) continue;
+      const idStr = String(id);
+      const label = row[labelField] ?? id;
+      out.set(idStr, String(label));
+    }
+    return out;
+  }, [result.data, labelField]);
+  return { map, loading: result.loading };
+}

package/src/hooks/use-store.ts

@@ -0,0 +1,47 @@
+import type { Store } from "@cosmicdrift/kumiko-headless";
+import { useRef, useSyncExternalStore } from "react";
+
+// React-Bindings für Kumikos Store-Primitive (`createStore` aus
+// @cosmicdrift/kumiko-headless). Beide Hooks sind dünne Wrapper um React's
+// useSyncExternalStore — die ganze Subscribe/Notify-Mechanik lebt im
+// Store selbst, hier wird nur React verdrahtet.
+//
+// useStore: gibt den ganzen Snapshot zurück. Re-rendert wenn der
+// Store seine Identität wechselt. Object.is-Gate im Store selbst
+// verhindert no-op-Updates.
+//
+// useStoreSelector: gibt eine abgeleitete Sicht zurück. Selectors die
+// Object-/Array-Literale zurückgeben (z.B. `s => ({ a, b })`) erzeugen
+// pro Render eine neue Identität — useSyncExternalStore würde das als
+// "Change" lesen und in eine Re-Render-Schleife laufen. Der dritte
+// Arg `equals` dient genau dafür: gleiche Auswahl → cached
+// Identität zurück, kein Re-Render.
+
+export function useStore<T>(store: Store<T>): T {
+  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+
+export function useStoreSelector<T, S>(
+  store: Store<T>,
+  select: (snapshot: T) => S,
+  equals: (a: S, b: S) => boolean = Object.is,
+): S {
+  // Cache der letzten Auswahl. Beim nächsten getSnapshot-Call vergleicht
+  // der Wrapper die neu berechnete Auswahl mit dem Cache und gibt — falls
+  // gleich — die cached Identität zurück. Das ist der Trick, der
+  // Selector-Returns wie `s => ({ a, b })` stabil hält.
+  const lastSelected = useRef<S>(undefined as S);
+  const initialized = useRef(false);
+
+  const getSelectedSnapshot = (): S => {
+    const next = select(store.getSnapshot());
+    if (initialized.current && equals(lastSelected.current, next)) {
+      return lastSelected.current;
+    }
+    lastSelected.current = next;
+    initialized.current = true;
+    return next;
+  };
+
+  return useSyncExternalStore(store.subscribe, getSelectedSnapshot, getSelectedSnapshot);
+}

package/src/i18n-defaults.ts

@@ -0,0 +1,94 @@
+// Framework-Default-Bundle. Strings die die Renderer-Components hart
+// brauchen (Save/Cancel/Delete-Buttons, Empty-States, Search-Placeholder,
+// Nav-Toggle-aria-Labels, Validation-Reasons). createKumikoApp hängt das
+// als ALLERLETZTEN Fallback in den LocaleProvider — Apps können
+// einzelne Keys via clientFeatures.translations überschreiben.
+//
+// Convention: alle Keys mit `kumiko.`-Prefix damit sie nicht mit
+// App-Keys kollidieren. Sub-Pfade gruppieren nach Bereich (actions /
+// list / nav / form / validation).
+
+import type { TranslationsByLocale } from "./i18n";
+
+export const kumikoDefaultTranslations: TranslationsByLocale = {
+  de: {
+    // Actions — Buttons in RenderEdit, RenderList, Confirm-Dialogen.
+    "kumiko.actions.save": "Speichern",
+    "kumiko.actions.cancel": "Abbrechen",
+    "kumiko.actions.delete": "Löschen",
+    "kumiko.actions.delete-confirm": "Wirklich löschen?",
+    "kumiko.actions.reload": "Neu laden",
+    "kumiko.actions.create": "Neu",
+
+    // List — DataTable Toolbar, Empty-State, Search.
+    "kumiko.list.search-placeholder": "Suchen…",
+    "kumiko.list.empty.title": "Noch keine Einträge.",
+    "kumiko.list.empty.hint": "Lege den ersten an, um loszulegen.",
+    "kumiko.list.no-entries": "Keine Einträge.",
+
+    // Combobox — Tier 2.1c Searchable-Select.
+    "kumiko.combobox.search-placeholder": "Suchen…",
+    "kumiko.combobox.empty": "Keine Treffer.",
+    "kumiko.combobox.loading": "Lade…",
+    "kumiko.combobox.placeholder": "—",
+
+    // Nav — Sidebar Tree (Toggle-aria-Labels).
+    "kumiko.nav.expand": "Aufklappen",
+    "kumiko.nav.collapse": "Zuklappen",
+
+    // Dialog — Confirm-Buttons + Close-aria-Label.
+    "kumiko.dialog.confirm": "Bestätigen",
+    "kumiko.dialog.cancel": "Abbrechen",
+    "kumiko.dialog.close": "Schließen",
+
+    // Form — Standard-Errors (App-Code kann eigene zod-Reasons nutzen,
+    // diese sind die letzte Sicherheitsschicht).
+    "kumiko.form.error.generic": "Etwas ist schiefgegangen.",
+    "kumiko.form.error.version-conflict":
+      "Datensatz wurde zwischenzeitlich geändert. Lade neu und versuche es erneut.",
+
+    // Validation — Default-Reason-Codes aus dem Framework. App-Code
+    // kann eigene Codes via Validation-Hooks reinwerfen; die hier sind
+    // die generischen.
+    "kumiko.validation.required": "Pflichtfeld.",
+    "kumiko.validation.invalid": "Ungültiger Wert.",
+    "kumiko.validation.too-short": "Zu kurz (mindestens {min} Zeichen).",
+    "kumiko.validation.too-long": "Zu lang (höchstens {max} Zeichen).",
+    "kumiko.validation.out-of-range": "Wert außerhalb des erlaubten Bereichs.",
+  },
+  en: {
+    "kumiko.actions.save": "Save",
+    "kumiko.actions.cancel": "Cancel",
+    "kumiko.actions.delete": "Delete",
+    "kumiko.actions.delete-confirm": "Confirm delete?",
+    "kumiko.actions.reload": "Reload",
+    "kumiko.actions.create": "New",
+
+    "kumiko.list.search-placeholder": "Search…",
+    "kumiko.list.empty.title": "No entries yet.",
+    "kumiko.list.empty.hint": "Create the first one to get started.",
+    "kumiko.list.no-entries": "No entries.",
+
+    "kumiko.combobox.search-placeholder": "Search…",
+    "kumiko.combobox.empty": "No matches.",
+    "kumiko.combobox.loading": "Loading…",
+    "kumiko.combobox.placeholder": "—",
+
+    "kumiko.nav.expand": "Expand",
+    "kumiko.nav.collapse": "Collapse",
+
+    "kumiko.dialog.confirm": "Confirm",
+    "kumiko.dialog.cancel": "Cancel",
+    "kumiko.dialog.close": "Close",
+
+    "kumiko.form.error.generic": "Something went wrong.",
+    "kumiko.form.error.version-conflict":
+      "Record was modified in the meantime. Reload and try again.",
+
+    "kumiko.validation.required": "Required.",
+    "kumiko.validation.invalid": "Invalid value.",
+    "kumiko.validation.too-short": "Too short (at least {min} characters).",
+    "kumiko.validation.too-long": "Too long (at most {max} characters).",
+    "kumiko.validation.out-of-range": "Value out of allowed range.",
+  },
+};