@cosmicdrift/kumiko-renderer 0.146.4 → 0.147.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.146.4",
+  "version": "0.147.0",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -15,8 +15,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.146.4",
-    "@cosmicdrift/kumiko-headless": "0.146.4",
+    "@cosmicdrift/kumiko-framework": "0.147.0",
+    "@cosmicdrift/kumiko-headless": "0.147.0",
     "react": "^19.2.6"
   },
   "devDependencies": {

package/src/__tests__/format-when.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from "bun:test";
+import { formatWhen } from "../format-when";
+
+describe("formatWhen", () => {
+  test("formats a parseable ISO timestamp", () => {
+    expect(formatWhen("2024-01-01T00:00:00.000Z")).not.toBe("2024-01-01T00:00:00.000Z");
+  });
+
+  test("falls back to the raw value on an unparseable input", () => {
+    expect(formatWhen("garbage")).toBe("garbage");
+  });
+});

package/src/app/kumiko-screen.tsx

@@ -52,6 +52,10 @@ function evalRowExtractor(
   return Object.fromEntries(Object.entries(extractor.map).map(([to, from]) => [to, row[from]]));
 }
 
+function isWriteHandlerRowAction(action: RowAction): action is RowActionWriteHandler {
+  return action.kind === "writeHandler" || action.kind === undefined;
+}
+
 // KumikoScreen picks up a ScreenDefinition from the schema by qn and
 // routes it to the right renderer based on `screen.type`. Command
 // qualification (`<feature>:write:<entity>:create` etc.) happens here
@@ -877,8 +881,8 @@ function EntityListBody({
           };
         }
         if (dispatcher === undefined) return null;
-        if (action.kind !== "writeHandler" && action.kind !== undefined) return null;
-        const writeAction = action as RowActionWriteHandler;
+        if (!isWriteHandlerRowAction(action)) return null;
+        const writeAction = action;
         const writeActionVisible = writeAction.visible;
         return {
           id: writeAction.id,
@@ -946,7 +950,16 @@ function EntityListBody({
           }),
           onTrigger: async () => {
             const payload = action.payload ?? {};
-            await dispatcher.write(action.handler, payload);
+            const result = await dispatcher.write(action.handler, payload);
+            // Gleicher Surfacing-Zwang wie bei rowActions (Prod-Bug
+            // 2026-06-07): ein verschlucktes Failure-Result sah wie
+            // "nichts passiert" aus.
+            if (!result.isSuccess) {
+              throw new WriteFailedError(
+                result.error,
+                dispatcherErrorText(result.error, effectiveTranslate),
+              );
+            }
           },
         };
       })
@@ -1112,7 +1125,7 @@ function ProjectionListBody({
       // Failure-Result MUSS zum Error werden (sonst schließt der Confirm-
       // Dialog kommentarlos).
       if (dispatcher === undefined) continue;
-      const writeAction = action as RowActionWriteHandler;
+      const writeAction = action;
       const writeVisible = writeAction.visible;
       out.push({
         id: writeAction.id,
@@ -1170,7 +1183,16 @@ function ProjectionListBody({
           confirmLabel: effectiveTranslate(action.confirmLabel),
         }),
         onTrigger: async () => {
-          await dispatcher.write(action.handler, action.payload ?? {});
+          const result = await dispatcher.write(action.handler, action.payload ?? {});
+          // Gleicher Surfacing-Zwang wie bei rowActions (Prod-Bug
+          // 2026-06-07): ein verschlucktes Failure-Result sah wie
+          // "nichts passiert" aus.
+          if (!result.isSuccess) {
+            throw new WriteFailedError(
+              result.error,
+              dispatcherErrorText(result.error, effectiveTranslate),
+            );
+          }
         },
       });
     }

package/src/components/render-edit.tsx

@@ -247,8 +247,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     [screen, entity, snapshot.values, translate, featureName],
   );
 
-  // isFormEditable, not "hasEditableField" (653/2) — true for an extension
-  // section with no fields of its own too (it carries its own dirty/save).
+  // true for an extension section with no fields of its own too (it carries its own dirty/save).
   const isFormEditable = hasEditableSection(vm.sections);
 
   // Persistiert alle composed Extension-Sections mit der aufgelösten entityId.

package/src/components/render-list.tsx

@@ -148,7 +148,7 @@ export function RenderList(props: RenderListProps): ReactNode {
   // wären Column-Header raw i18n-Keys.
   const t = useTranslation();
   const translate: Translate = translateProp ?? t;
-  const { DataTable, Button, Dialog, Input, Text } = usePrimitives();
+  const { DataTable, Button, Dialog, Input, Text, Banner } = usePrimitives();
 
   // Local Search-Buffer + Debounce. Externe Änderungen (Browser-Back,
   // Cross-Component-Reset) spiegeln wir per Sync-Effect zurück; Tipps
@@ -280,7 +280,13 @@ export function RenderList(props: RenderListProps): ReactNode {
         {hasHeaderSlot && <ListHeaderSlotMount screen={screen} />}
         {hasToolbarActions &&
           toolbarActions.map((a) => (
-            <ToolbarActionView key={a.id} action={a} Button={Button} Dialog={Dialog} />
+            <ToolbarActionView
+              key={a.id}
+              action={a}
+              Button={Button}
+              Dialog={Dialog}
+              Banner={Banner}
+            />
           ))}
         {onCreate !== undefined && (
           <Button variant="primary" onClick={onCreate} testId="render-list-create">
@@ -423,18 +429,29 @@ function ToolbarActionView({
   action,
   Button,
   Dialog,
+  Banner,
 }: {
   readonly action: ToolbarActionButton;
   readonly Button: ReturnType<typeof usePrimitives>["Button"];
   readonly Dialog: ReturnType<typeof usePrimitives>["Dialog"];
+  readonly Banner: ReturnType<typeof usePrimitives>["Banner"];
 }): ReactNode {
   const [busy, setBusy] = useState(false);
   const [confirmOpen, setConfirmOpen] = useState(false);
+  // Toolbar-Actions haben (anders als rowActions, die über die DataTable-
+  // Primitive laufen) keine Toast-Primitive zur Verfügung — ein inline
+  // Error-Banner ist der surfacing-Pfad hier. Gleicher Grund wie bei
+  // rowActions (Prod-Bug 2026-06-07): ein verschlucktes Failure-Result
+  // sieht für den User wie "nichts passiert" aus.
+  const [errorText, setErrorText] = useState<string | null>(null);
 
   const trigger = async (): Promise<void> => {
     setBusy(true);
+    setErrorText(null);
     try {
       await action.onTrigger();
+    } catch (e) {
+      setErrorText(e instanceof Error ? e.message : String(e));
     } finally {
       setBusy(false);
     }
@@ -469,6 +486,11 @@ function ToolbarActionView({
         onConfirm={trigger}
         testId={`render-list-toolbar-action-${action.id}-dialog`}
       />
+      {errorText !== null && (
+        <Banner variant="error" testId={`render-list-toolbar-action-${action.id}-error`}>
+          {errorText}
+        </Banner>
+      )}
     </>
   );
 }

package/src/format-when.ts

@@ -0,0 +1,6 @@
+// Shared timestamp formatter for operator screens (audit log, job runs) —
+// falls back to the raw ISO string on an unparseable value instead of "Invalid Date".
+export function formatWhen(value: string): string {
+  const d = new Date(value);
+  return Number.isNaN(d.getTime()) ? value : d.toLocaleString();
+}

package/src/hooks/__tests__/use-ai-text.test.tsx

@@ -0,0 +1,176 @@
+import { describe, expect, test } from "bun:test";
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { DispatcherProvider } from "../../context/dispatcher-context";
+import { useAiTextAction, useCompletion } from "../use-ai-text";
+
+function makeDispatcher(query: Dispatcher["query"]): Dispatcher {
+  return {
+    query,
+    write: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function wrapperFor(dispatcher: Dispatcher) {
+  return ({ children }: { readonly children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useAiTextAction", () => {
+  test("success → state='success', result carries the text", async () => {
+    const dispatcher = makeDispatcher((async (_type: string, payload: unknown) => ({
+      isSuccess: true,
+      data: {
+        type: "text",
+        text: `echo:${(payload as { text: string }).text}`,
+        usage: { inputTokens: 1, outputTokens: 1 },
+      },
+    })) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useAiTextAction(), { wrapper: wrapperFor(dispatcher) });
+
+    expect(result.current.state).toBe("idle");
+    await act(async () => {
+      await result.current.run({ mode: "correct", text: "hi" });
+    });
+
+    expect(result.current.state).toBe("success");
+    expect(result.current.result).toEqual({
+      type: "text",
+      text: "echo:hi",
+      usage: { inputTokens: 1, outputTokens: 1 },
+    });
+    expect(result.current.error).toBeNull();
+  });
+
+  test("cap_exceeded error → state='cap-exceeded'", async () => {
+    const dispatcher = makeDispatcher((async () => ({
+      isSuccess: false,
+      error: { code: "cap_exceeded", message: "capped", i18nKey: "errors.cap" },
+    })) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useAiTextAction(), { wrapper: wrapperFor(dispatcher) });
+
+    await act(async () => {
+      await result.current.run({ mode: "correct", text: "hi" });
+    });
+
+    expect(result.current.state).toBe("cap-exceeded");
+    expect(result.current.error?.code).toBe("cap_exceeded");
+  });
+
+  test("feature_disabled error → state='unavailable' (graceful degradation)", async () => {
+    const dispatcher = makeDispatcher((async () => ({
+      isSuccess: false,
+      error: { code: "feature_disabled", message: "off", i18nKey: "errors.disabled" },
+    })) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useAiTextAction(), { wrapper: wrapperFor(dispatcher) });
+
+    await act(async () => {
+      await result.current.run({ mode: "complete", text: "hi" });
+    });
+
+    expect(result.current.state).toBe("unavailable");
+  });
+
+  test("reset clears state/result/error back to idle", async () => {
+    const dispatcher = makeDispatcher((async () => ({
+      isSuccess: false,
+      error: { code: "conflict", message: "boom", i18nKey: "errors.conflict" },
+    })) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useAiTextAction(), { wrapper: wrapperFor(dispatcher) });
+    await act(async () => {
+      await result.current.run({ mode: "correct", text: "hi" });
+    });
+    expect(result.current.state).toBe("error");
+
+    act(() => result.current.reset());
+    expect(result.current.state).toBe("idle");
+    expect(result.current.error).toBeNull();
+    expect(result.current.result).toBeNull();
+  });
+});
+
+describe("useCompletion", () => {
+  test("debounces requestCompletion — only the last call within the window fires", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async (_type: string, payload: unknown) => {
+      calls++;
+      return {
+        isSuccess: true,
+        data: {
+          type: "text",
+          text: `suggestion for "${(payload as { text: string }).text}"`,
+          usage: { inputTokens: 1, outputTokens: 1 },
+        },
+      };
+    }) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useCompletion(20), { wrapper: wrapperFor(dispatcher) });
+
+    act(() => {
+      result.current.requestCompletion("a");
+      result.current.requestCompletion("ab");
+      result.current.requestCompletion("abc");
+    });
+
+    await waitFor(() => expect(result.current.suggestion).not.toBeNull(), { timeout: 1000 });
+
+    expect(calls).toBe(1);
+    expect(result.current.suggestion).toBe('suggestion for "abc"');
+  });
+
+  test("empty text resets immediately without a request", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async () => {
+      calls++;
+      return {
+        isSuccess: true,
+        data: { type: "text", text: "x", usage: { inputTokens: 1, outputTokens: 1 } },
+      };
+    }) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useCompletion(10), { wrapper: wrapperFor(dispatcher) });
+
+    act(() => {
+      result.current.requestCompletion("");
+    });
+    await new Promise((r) => setTimeout(r, 30));
+
+    expect(calls).toBe(0);
+    expect(result.current.suggestion).toBeNull();
+  });
+
+  test("clear cancels a pending debounce and resets the suggestion", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async () => {
+      calls++;
+      return {
+        isSuccess: true,
+        data: { type: "text", text: "x", usage: { inputTokens: 1, outputTokens: 1 } },
+      };
+    }) as unknown as Dispatcher["query"]);
+
+    const { result } = renderHook(() => useCompletion(30), { wrapper: wrapperFor(dispatcher) });
+
+    act(() => {
+      result.current.requestCompletion("hello");
+    });
+    act(() => result.current.clear());
+    await new Promise((r) => setTimeout(r, 60));
+
+    expect(calls).toBe(0);
+    expect(result.current.suggestion).toBeNull();
+  });
+});

package/src/hooks/use-ai-text.ts

@@ -0,0 +1,171 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context";
+
+// AiTextField/AiTextArea's client-side surface. Deliberately duplicates the
+// wire-contract shape from kumiko-enterprise's `ai-text` feature instead of
+// importing it — this package is public NPM, ai-text is a private Enterprise
+// package, and the widgets only ever talk HTTP (ai-text-primitive plan doc,
+// Architecture Decision 1). Keep these in lockstep with
+// kumiko-enterprise/packages/ai-text/src/{modes,feature}.ts by hand; there's
+// no compile-time link between the two repos.
+
+export const AI_TEXT_RUN_QN = "ai-text:query:run";
+
+export type AiTextMode = "complete" | "correct" | "translate" | "rewrite";
+export type AiTextRewriteStyle = "formal" | "casual" | "concise" | "expand";
+
+export type AiTextRunPayload =
+  | { readonly mode: "complete"; readonly text: string }
+  | { readonly mode: "correct"; readonly text: string }
+  | { readonly mode: "translate"; readonly text: string; readonly targetLanguage: string }
+  | { readonly mode: "rewrite"; readonly text: string; readonly style?: AiTextRewriteStyle };
+
+export type AiTextUsage = { readonly inputTokens: number; readonly outputTokens: number };
+
+export type AiTextRunResult =
+  | { readonly type: "text"; readonly text: string; readonly usage: AiTextUsage }
+  | { readonly type: "error"; readonly reason: string; readonly usage: AiTextUsage };
+
+// =============================================================================
+// useAiTextAction — one-shot request/response, any mode
+// =============================================================================
+//
+// v1 has no streaming (ai-text-primitive plan doc, sequencing note —
+// SSE-with-auth-reuse needs a framework-core `r.streamHandler` primitive,
+// tracked separately). `complete` goes through this same request/response
+// path as correct/translate/rewrite; `useCompletion` below adds debounce on
+// top for the ghost-text use-case specifically.
+
+export type AiTextActionState =
+  | "idle"
+  | "loading"
+  | "success"
+  | "error"
+  | "cap-exceeded"
+  | "unavailable";
+
+export type UseAiTextActionResult = {
+  readonly run: (payload: AiTextRunPayload) => Promise<AiTextRunResult | null>;
+  readonly state: AiTextActionState;
+  readonly result: AiTextRunResult | null;
+  readonly error: DispatcherError | null;
+  readonly reset: () => void;
+};
+
+function stateForError(error: DispatcherError): AiTextActionState {
+  if (error.code === "cap_exceeded" || error.code === "rate_limited") return "cap-exceeded";
+  if (error.code === "feature_disabled") return "unavailable";
+  return "error";
+}
+
+export function useAiTextAction(): UseAiTextActionResult {
+  const dispatcher = useDispatcher();
+  const [state, setState] = useState<AiTextActionState>("idle");
+  const [result, setResult] = useState<AiTextRunResult | null>(null);
+  const [error, setError] = useState<DispatcherError | null>(null);
+
+  // Track the in-flight call so a newer `run()` cancels an older one, and
+  // unmount doesn't set state after the component is gone — same pattern
+  // as useQuery's activeCtrl.
+  const activeCtrl = useRef<AbortController | null>(null);
+  useEffect(() => {
+    return () => {
+      activeCtrl.current?.abort();
+    };
+  }, []);
+
+  const run = useCallback(
+    async (payload: AiTextRunPayload): Promise<AiTextRunResult | null> => {
+      activeCtrl.current?.abort();
+      const ctrl = new AbortController();
+      activeCtrl.current = ctrl;
+
+      setState("loading");
+      setError(null);
+
+      const res = await dispatcher.query<AiTextRunResult>(AI_TEXT_RUN_QN, payload, {
+        signal: ctrl.signal,
+      });
+      if (ctrl.signal.aborted) return null;
+
+      if (!res.isSuccess) {
+        if (res.error.code === "aborted") return null;
+        setError(res.error);
+        setState(stateForError(res.error));
+        return null;
+      }
+
+      setResult(res.data);
+      setState("success");
+      return res.data;
+    },
+    [dispatcher],
+  );
+
+  const reset = useCallback(() => {
+    activeCtrl.current?.abort();
+    setState("idle");
+    setResult(null);
+    setError(null);
+  }, []);
+
+  return { run, state, result, error, reset };
+}
+
+// =============================================================================
+// useCompletion — debounced ghost-text for AiTextField/AiTextArea
+// =============================================================================
+//
+// Debounce exists to keep the request-rate down against the monthly cap,
+// not for UX polish — every keystroke would otherwise burn a request.
+
+export type UseCompletionResult = {
+  readonly suggestion: string | null;
+  readonly state: AiTextActionState;
+  readonly error: DispatcherError | null;
+  /** Debounced — schedules a completion request `debounceMs` after the
+   *  last call. Calling again before the timer fires replaces it. */
+  readonly requestCompletion: (text: string) => void;
+  /** Cancels any pending/in-flight request and clears the suggestion. */
+  readonly clear: () => void;
+};
+
+const DEFAULT_DEBOUNCE_MS = 500;
+
+export function useCompletion(debounceMs: number = DEFAULT_DEBOUNCE_MS): UseCompletionResult {
+  const { run, state, result, error, reset } = useAiTextAction();
+  const timerRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== undefined) {
+      clearTimeout(timerRef.current);
+      timerRef.current = undefined;
+    }
+  }, []);
+
+  const requestCompletion = useCallback(
+    (text: string) => {
+      clearTimer();
+      if (text.length === 0) {
+        reset();
+        return;
+      }
+      timerRef.current = setTimeout(() => {
+        void run({ mode: "complete", text });
+      }, debounceMs);
+    },
+    [clearTimer, reset, run, debounceMs],
+  );
+
+  const clear = useCallback(() => {
+    clearTimer();
+    reset();
+  }, [clearTimer, reset]);
+
+  useEffect(() => clearTimer, [clearTimer]);
+
+  const suggestion = result?.type === "text" ? result.text : null;
+
+  return { suggestion, state, error, requestCompletion, clear };
+}

package/src/hooks/use-mutation.ts

@@ -1,5 +1,5 @@
 import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { useDispatcher } from "../context/dispatcher-context";
 
 // React wrapper around dispatcher.write — the write-side sibling of
@@ -24,24 +24,34 @@ export function useMutation<TData = unknown>(type: string): UseMutationResult<TD
   const [pending, setPending] = useState(false);
   const [error, setError] = useState<DispatcherError | null>(null);
   const [data, setData] = useState<TData | null>(null);
+  // Sequence guard: `mutate` has no abort (unlike useQuery's GETs, a write
+  // already landed server-side and can't be cancelled). Two overlapping
+  // calls on one instance (e.g. two list-row actions) must not let the
+  // first-to-resolve clobber pending/error/data set by the second — only
+  // the most recently STARTED call's outcome may update shared state.
+  const sequence = useRef(0);
 
   const mutate = useCallback(
     async (payload: unknown): Promise<WriteResult<TData>> => {
+      const callSeq = ++sequence.current;
       setPending(true);
       setError(null);
       const result = await dispatcher.write<TData>(type, payload);
-      if (result.isSuccess) {
-        setData(result.data);
-      } else {
-        setError(result.error);
+      if (callSeq === sequence.current) {
+        if (result.isSuccess) {
+          setData(result.data);
+        } else {
+          setError(result.error);
+        }
+        setPending(false);
       }
-      setPending(false);
       return result;
     },
     [dispatcher, type],
   );
 
   const reset = useCallback(() => {
+    sequence.current++; // invalidate any in-flight mutate's late update
     setPending(false);
     setError(null);
     setData(null);

package/src/i18n-defaults.ts

@@ -63,6 +63,20 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.dialog.cancel": "Abbrechen",
     "kumiko.dialog.close": "Schließen",
 
+    // AiTextField/AiTextArea — Ghost-Text-Hint, Toolbar-Aria-Labels, Diff-Dialog.
+    "kumiko.aiText.acceptHint": "Tab = übernehmen, Esc = verwerfen",
+    "kumiko.aiText.correct": "Korrigieren",
+    "kumiko.aiText.translate": "Übersetzen",
+    "kumiko.aiText.rewrite": "Umschreiben",
+    "kumiko.aiText.diff.before": "Vorher",
+    "kumiko.aiText.diff.after": "Nachher",
+    "kumiko.aiText.diff.generating": "Wird generiert…",
+    "kumiko.aiText.style.formal": "Formell",
+    "kumiko.aiText.style.casual": "Locker",
+    "kumiko.aiText.style.concise": "Kompakt",
+    "kumiko.aiText.style.expand": "Ausführlicher",
+    "kumiko.aiText.capExceeded": "Monatliches AI-Limit erreicht.",
+
     // Row-Actions — Fehler-Toast wenn ein Action-Write fehlschlägt.
     "kumiko.rowAction.failed": "Aktion fehlgeschlagen",
 
@@ -128,7 +142,10 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "errors.unconfigured": "Diese Funktion ist noch nicht konfiguriert.",
     "errors.internal": "Etwas ist schiefgegangen. Bitte versuche es später erneut.",
     "errors.rate_limited": "Zu viele Anfragen. Bitte versuche es in Kürze erneut.",
+    "errors.cap.exceeded":
+      "Limit erreicht. Bitte Tarif upgraden oder auf die nächste Periode warten.",
     "errors.download.urlMissing": "Download nicht verfügbar — bitte versuche es erneut.",
+    "auth.errors.originNotAllowed": "Zugriff von dieser Herkunft ist nicht erlaubt.",
   },
   en: {
     "kumiko.actions.save": "Save",
@@ -171,6 +188,19 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "kumiko.dialog.cancel": "Cancel",
     "kumiko.dialog.close": "Close",
 
+    "kumiko.aiText.acceptHint": "Tab = accept, Esc = discard",
+    "kumiko.aiText.correct": "Correct",
+    "kumiko.aiText.translate": "Translate",
+    "kumiko.aiText.rewrite": "Rewrite",
+    "kumiko.aiText.diff.before": "Before",
+    "kumiko.aiText.diff.after": "After",
+    "kumiko.aiText.diff.generating": "Generating…",
+    "kumiko.aiText.style.formal": "Formal",
+    "kumiko.aiText.style.casual": "Casual",
+    "kumiko.aiText.style.concise": "Concise",
+    "kumiko.aiText.style.expand": "Expand",
+    "kumiko.aiText.capExceeded": "Monthly AI limit reached.",
+
     "kumiko.rowAction.failed": "Action failed",
 
     "kumiko.config.source.user": "My value",
@@ -221,6 +251,8 @@ export const kumikoDefaultTranslations: TranslationsByLocale = {
     "errors.unconfigured": "This feature isn't configured yet.",
     "errors.internal": "Something went wrong. Please try again later.",
     "errors.rate_limited": "Too many requests. Please try again shortly.",
+    "errors.cap.exceeded": "Limit reached. Upgrade your plan or wait for the next period.",
     "errors.download.urlMissing": "Download unavailable — please try again.",
+    "auth.errors.originNotAllowed": "Requests from this origin are not allowed.",
   },
 };

package/src/i18n.tsx

@@ -40,9 +40,8 @@ export function translationsByLocaleFromKeys(source: TranslationsByKey): Transla
   const out: Record<string, Record<string, string>> = {};
   for (const [key, byLocale] of Object.entries(source)) {
     for (const [locale, value] of Object.entries(byLocale)) {
-      const bucket = out[locale] ?? {};
-      bucket[key] = value;
-      out[locale] = bucket;
+      out[locale] ??= {};
+      out[locale][key] = value;
     }
   }
   return out;

package/src/index.ts

@@ -59,11 +59,23 @@ export {
   useDispatcherStatus,
   useOptionalDispatcher,
 } from "./context/dispatcher-context";
+export { formatWhen } from "./format-when";
 export {
   REFERENCE_COMBOBOX_LIMIT,
   REFERENCE_LIST_LOOKUP_LIMIT,
   REFERENCE_SEARCH_DEBOUNCE_MS,
 } from "./hooks/reference-limits";
+export type {
+  AiTextActionState,
+  AiTextMode,
+  AiTextRewriteStyle,
+  AiTextRunPayload,
+  AiTextRunResult,
+  AiTextUsage,
+  UseAiTextActionResult,
+  UseCompletionResult,
+} from "./hooks/use-ai-text";
+export { AI_TEXT_RUN_QN, useAiTextAction, useCompletion } from "./hooks/use-ai-text";
 export type { UseDisclosureResult } from "./hooks/use-disclosure";
 export { useDisclosure } from "./hooks/use-disclosure";
 export type { UseFormOptions, UseFormResult } from "./hooks/use-form";
@@ -125,6 +137,7 @@ export type {
   TextProps,
 } from "./primitives";
 export { PrimitivesProvider, usePrimitives } from "./primitives";
+export { sortByAccessor } from "./sort-by-accessor";
 export type { LiveEvent, LiveEventSubscriber, LiveEventsProviderProps } from "./sse/live-events";
 export { LiveEventsProvider, useLiveEvents } from "./sse/live-events";
 export type {

package/src/primitives.tsx

@@ -560,6 +560,10 @@ export type SectionProps = {
    *  übernehmen"). Web rendert standalone eine abgehobene Footer-Row
    *  (border-t), innerhalb eines Forms eine rechtsbündige Button-Reihe. */
   readonly actions?: ReactNode;
+  /** "destructive" marks the Section as a warning/danger area (e.g. account
+   *  deletion, restrict processing) — border color only, no content change.
+   *  Default "default" (normal card border). */
+  readonly variant?: "default" | "destructive";
   readonly testId?: string;
 };
 

package/src/sort-by-accessor.ts

@@ -0,0 +1,20 @@
+import type { DataTableSort } from "./primitives";
+
+/** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
+ *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
+ *  callers pass whatever the DataTable reports). */
+export function sortByAccessor<TRow>(
+  rows: readonly TRow[],
+  sort: DataTableSort | null,
+  accessors: Readonly<Record<string, (row: TRow) => string | number>>,
+): readonly TRow[] {
+  if (sort === null) return rows;
+  const accessor = accessors[sort.field];
+  if (accessor === undefined) return rows;
+  const factor = sort.dir === "asc" ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const av = accessor(a);
+    const bv = accessor(b);
+    return av < bv ? -factor : av > bv ? factor : 0;
+  });
+}