@cosmicdrift/kumiko-renderer 1.0.0 → 2.0.0

package/src/app/projection-detail-shim.ts

@@ -0,0 +1,72 @@
+// Shim für ProjectionDetail-Renderer (analog zu projection-list-shim.ts /
+// config-edit-shim.ts).
+//
+// RenderEdit verlangt ein `entity: EntityDefinition` + ein
+// `screen: EntityEditScreenDefinition`-Pair, nutzt davon aber nur
+// `entity.fields` (Feld-Typ für den Input-Renderer) und `screen.layout`
+// (welche Felder in welchen Sections). Ein projectionDetail-Screen ist
+// query-getrieben und hat KEINE Entity — die zwei Helper hier shapen den
+// Input ad-hoc um, damit RenderEdit reused werden kann.
+//
+// Der strukturelle Read-Only-Beweis liegt in synthesizeProjectionDetailScreen:
+// JEDES Feld wird hart auf readOnly:true gesetzt (nicht nur was der Author im
+// Layout gesetzt hat) — hasEditableSection() liest genau dieses Flag und
+// blendet den Save-Button aus, wenn kein Feld editierbar ist. Der Author kann
+// diese Garantie nicht versehentlich umgehen.
+//
+// Selbe Schulden-Reservation wie bei den anderen Shims: greift RenderEdit
+// künftig auf weitere EntityDefinition-Felder (transitions, idType) zu, oder
+// cross-referenziert ein Boot-Validator die schema.entities-Map, brechen die
+// Type-Lies hier silent — dann ist Zeit für eine echte RenderProjectionDetail-
+// Komponente.
+
+import type {
+  EditLayout,
+  EntityDefinition,
+  EntityEditScreenDefinition,
+  ProjectionDetailScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import {
+  isExtensionEditSection,
+  normalizeEditField,
+  PROJECTION_DETAIL_ENTITY as PROJECTION_DETAIL_PSEUDO_ENTITY,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+
+/** Minimale EntityDefinition aus den Layout-Feldern: jedes Feld ein Text-
+ *  Feld — computeEditViewModel liest nur `fields[<f>].type`, Text reicht für
+ *  eine reine Anzeige (kein Select/Number-spezifisches Rendering nötig). */
+export function synthesizeProjectionDetailEntity(layout: EditLayout): EntityDefinition {
+  const fields: Record<string, { type: "text" }> = {};
+  for (const section of layout.sections) {
+    if (isExtensionEditSection(section)) continue; // rejected at boot, defensive here
+    for (const spec of section.fields) {
+      fields[normalizeEditField(spec).field] = { type: "text" };
+    }
+  }
+  return { fields } as unknown as EntityDefinition;
+}
+
+/** Wandelt ein ProjectionDetailScreenDefinition in die EntityEditScreen-Shape
+ *  die RenderEdit erwartet — mit jedem Feld hart auf readOnly:true erzwungen. */
+export function synthesizeProjectionDetailScreen(
+  screen: ProjectionDetailScreenDefinition,
+): EntityEditScreenDefinition {
+  const sections = screen.layout.sections.map((section) => {
+    if (isExtensionEditSection(section)) return section; // rejected at boot, defensive here
+    return {
+      ...section,
+      fields: section.fields.map((spec) => ({ ...normalizeEditField(spec), readOnly: true })),
+    };
+  });
+  return {
+    id: screen.id,
+    type: "entityEdit",
+    entity: PROJECTION_DETAIL_PSEUDO_ENTITY,
+    layout: { sections },
+    allowCreate: false,
+    allowDelete: false,
+    ...(screen.fieldLabels !== undefined && { fieldLabels: screen.fieldLabels }),
+    ...(screen.slots !== undefined && { slots: screen.slots }),
+    ...(screen.access !== undefined && { access: screen.access }),
+  };
+}

package/src/app/projection-list-shim.ts

@@ -0,0 +1,62 @@
+// Shim für ProjectionList-Renderer (analog action-form-shim.ts / config-edit-shim.ts).
+//
+// RenderList + computeListViewModel verlangen ein `entity: EntityDefinition` +
+// ein `screen: EntityListScreenDefinition`-Pair, nutzen davon aber nur
+// `entity.fields` (Spalten-Typ/Label) und die List-Felder des Screens
+// (columns/rowActions/…). Ein projectionList-Screen ist query-getrieben und hat
+// KEINE Entity — die zwei Helper hier shapen den Input ad-hoc um, damit die
+// bestehende List-Maschinerie reused werden kann. Die Query selbst wird NICHT
+// hierüber aufgelöst (der Body nimmt `screen.query` direkt).
+//
+// Selbe Schulden-Reservation wie bei den anderen Shims: greift die List-
+// Maschinerie künftig auf weitere EntityDefinition-Felder (transitions, idType,
+// derivedFields) oder cross-referenziert ein Boot-Validator die schema.entities-
+// Map, brechen die Type-Lies hier silent — dann ist Zeit für eine echte
+// query-native ListView-Komponente.
+
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  ListColumnSpec,
+  ProjectionListScreenDefinition,
+} from "@cosmicdrift/kumiko-framework/ui-types";
+import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
+
+const PROJECTION_PSEUDO_ENTITY = "__projection__";
+
+/** Minimale EntityDefinition aus den Column-Feldern: jedes Feld ein Text-Feld,
+ *  nicht sortierbar (eine Projection-Query hat keinen garantierten Server-Sort).
+ *  computeListViewModel liest nur `fields[<col>].type` → Text reicht; die
+ *  Präsentation kommt aus dem Column-Renderer + explizitem Label. */
+export function synthesizeProjectionEntity(columns: readonly ListColumnSpec[]): EntityDefinition {
+  const fields: Record<string, { type: "text"; sortable: false }> = {};
+  for (const col of columns) {
+    fields[normalizeListColumn(col).field] = { type: "text", sortable: false };
+  }
+  return { fields } as unknown as EntityDefinition;
+}
+
+/** Wandelt ein ProjectionListScreenDefinition in die EntityListScreen-Shape die
+ *  RenderList erwartet. `type` = "entityList" + Pseudo-Entity halten den Type-
+ *  Constraint; RenderList branched nicht auf `type` und liest `entity` nur für
+ *  Fehlermeldungen. Die List-Felder werden 1:1 durchgereicht. */
+export function synthesizeProjectionScreen(
+  screen: ProjectionListScreenDefinition,
+): EntityListScreenDefinition {
+  return {
+    id: screen.id,
+    type: "entityList",
+    entity: PROJECTION_PSEUDO_ENTITY,
+    columns: screen.columns,
+    ...(screen.rowRenderer !== undefined && { rowRenderer: screen.rowRenderer }),
+    ...(screen.cardRenderer !== undefined && { cardRenderer: screen.cardRenderer }),
+    ...(screen.rowActions !== undefined && { rowActions: screen.rowActions }),
+    ...(screen.toolbarActions !== undefined && { toolbarActions: screen.toolbarActions }),
+    ...(screen.pagination !== undefined && { pagination: screen.pagination }),
+    ...(screen.pageSize !== undefined && { pageSize: screen.pageSize }),
+    ...(screen.defaultSort !== undefined && { defaultSort: screen.defaultSort }),
+    ...(screen.searchable !== undefined && { searchable: screen.searchable }),
+    ...(screen.slots !== undefined && { slots: screen.slots }),
+    ...(screen.access !== undefined && { access: screen.access }),
+  };
+}

package/src/app/qn.ts

@@ -21,3 +21,16 @@ export function lastSegment(qn: string): string {
   const idx = qn.lastIndexOf(":");
   return idx < 0 ? qn : qn.slice(idx + 1);
 }
+
+/**
+ * Client-safe copy of framework `toKebab` (engine/qualified-name.ts).
+ * Must stay in sync — do NOT import from `@cosmicdrift/kumiko-framework/engine`
+ * here: that barrel pulls server deps into the browser bundle.
+ */
+export function toKebab(input: string): string {
+  return input
+    .replace(/\./g, "-")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+}

package/src/components/__tests__/render-field-app-locale.test.tsx

@@ -37,8 +37,10 @@ const testPrimitives: CorePrimitives = {
   Text: noop,
   Heading: noop,
   Dialog: noop,
+  Lightbox: noop,
   ConfigSourceBadge: noop,
   ConfigCascadeView: noop,
+  Link: noop,
 };
 
 function moneyField(): EditFieldViewModel {

package/src/components/render-edit-logic.ts

@@ -1,11 +1,14 @@
 import type { EditSectionViewModel, SubmitResult } from "@cosmicdrift/kumiko-headless";
 
-// A read-only inspector form — every field readOnly, no editable section — has
-// nothing to submit, so the renderer drops the Save button rather than show a
-// dead disabled one. An extension section carries its own dirty/save, so it
-// counts as editable.
+// Hides the Save button when no field is editable and no extension section
+// exists (extension carries its own dirty/save; a purely read-only form has nothing to submit).
+// Explicit-positive per kind (653/1), not `s.kind !== "fields"` — a future
+// third EditSectionViewModel member would otherwise default to "editable"
+// without anyone deciding that on purpose.
 export function hasEditableSection(sections: readonly EditSectionViewModel[]): boolean {
-  return sections.some((s) => s.kind !== "fields" || s.fields.some((f) => !f.readOnly));
+  return sections.some(
+    (s) => s.kind === "extension" || (s.kind === "fields" && s.fields.some((f) => !f.readOnly)),
+  );
 }
 
 // Single source of truth for the extension-section entity-id. The section mount

package/src/components/render-edit.tsx

@@ -76,6 +76,13 @@ export type RenderEditProps<TValues extends FormValues, TCtx = unknown> = {
   readonly onDelete?: () => Promise<void> | void;
   readonly onCancel?: () => void;
   readonly onReload?: () => void;
+  /** Copy-Link-Action (Issue #912) — nur in update-mode gesetzt (create-mode
+   *  hat noch keine entity-id, also keinen Permalink). Der Callback ist
+   *  bereits vollständig gebunden (URL-Bau + Clipboard passiert außerhalb,
+   *  in `@cosmicdrift/kumiko-renderer-web`'s RoutedScreen — dieses
+   *  platform-neutrale Package darf kein `navigator`/`window` anfassen,
+   *  siehe guard-renderer-boundaries). undefined = kein Button. */
+  readonly onCopyLink?: () => Promise<void> | void;
   /** i18n-key für den Submit-Button. Default: "kumiko.actions.save".
    *  Action-Forms (Tier 2.7d) übergeben hier ihren screen.submitLabel,
    *  damit "Speichern" durch domain-spezifischere Strings ersetzt
@@ -185,6 +192,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     onDelete,
     onCancel,
     onReload,
+    onCopyLink,
     submitLabel,
     labelAppendix,
     fieldAppendix,
@@ -201,6 +209,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   const translate = translateProp ?? t;
 
   const [confirmDeleteOpen, setConfirmDeleteOpen] = useState(false);
+  const [linkCopied, setLinkCopied] = useState(false);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [formError, setFormError] = useState<DispatcherError | null>(null);
   // Composed-Save: Extension-Sections melden hier ihren dirty-State (damit der
@@ -247,7 +256,8 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
     [screen, entity, snapshot.values, translate, featureName],
   );
 
-  const hasEditableField = hasEditableSection(vm.sections);
+  // 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.
   // false = eine Section schlug fehl (ihr i18n-Key landet im Banner). Ohne
@@ -335,6 +345,19 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
   // gegen Fehlklicks. Save bleibt rechts (primary affordance).
   const formActions = (
     <>
+      {onCopyLink !== undefined && (
+        <Button
+          type="button"
+          variant="secondary"
+          testId="render-edit-copy-link"
+          onClick={async () => {
+            await onCopyLink();
+            setLinkCopied(true);
+          }}
+        >
+          {translate(linkCopied ? "kumiko.actions.copyLinkCopied" : "kumiko.actions.copyLink")}
+        </Button>
+      )}
       {onDelete !== undefined && (
         <Button
           type="button"
@@ -355,7 +378,7 @@ export function RenderEdit<TValues extends FormValues, TCtx = unknown>(
           {translate("kumiko.actions.cancel")}
         </Button>
       )}
-      {hasEditableField && (
+      {isFormEditable && (
         <Button
           type="submit"
           disabled={(snapshot.isUnchanged && !extensionDirty) || isSubmitting}

package/src/components/render-field.tsx

@@ -1,5 +1,6 @@
 import type { EditFieldViewModel, FieldIssue } from "@cosmicdrift/kumiko-headless";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { toKebab } from "../app/qn";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits";
 import { useQuery } from "../hooks/use-query";
 import { useLocale } from "../i18n";
@@ -118,7 +119,7 @@ function ReferenceInput({
   // Tier 2.7e Cross-Feature: refFeature kann ≠ featureName sein
   // (z.B. items.assignee → users:query:user:list). Default ist
   // same-feature, kommt aus dem ViewModel (parseRefTarget).
-  const queryQn = `${refFeature}:query:${refEntity}:list`;
+  const queryQn = `${toKebab(refFeature)}:query:${toKebab(refEntity)}:list`;
   // Tier 2.7e Remote-Search: User tippt im Combobox → Server filtert
   // via existing list-payload `search`-Param (Tier 2.6c). Combobox
   // debounced den keystroke selbst (300ms) und ruft onSearchChange.

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/context/user-roles-context.tsx

@@ -0,0 +1,27 @@
+import { createContext, type ReactNode, useContext } from "react";
+
+// Threads the current user's roles through the tree so KumikoScreen can
+// gate role-restricted screens at render time (see #1203 — nav filtering
+// alone doesn't stop a direct-URL/screenQn hit on a role-gated screen).
+// Apps wire this from their `shell` render-prop, the same place they
+// already pass `user` to WorkspaceShell for nav filtering.
+//
+// undefined (no provider mounted, or `roles` not passed) means "roles
+// unknown" — deliberately distinct from `[]` ("authenticated, no
+// roles"). Both deny role-gated screens; only `undefined` also lets an
+// app without any role-gated screens skip wiring this entirely.
+
+const UserRolesContext = createContext<readonly string[] | undefined>(undefined);
+
+export type UserRolesProviderProps = {
+  readonly roles: readonly string[] | undefined;
+  readonly children: ReactNode;
+};
+
+export function UserRolesProvider({ roles, children }: UserRolesProviderProps): ReactNode {
+  return <UserRolesContext value={roles}>{children}</UserRolesContext>;
+}
+
+export function useUserRoles(): readonly string[] | undefined {
+  return useContext(UserRolesContext);
+}

package/src/format-when.ts

@@ -0,0 +1,11 @@
+import { toInstant } from "@cosmicdrift/kumiko-headless";
+
+// 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 {
+  try {
+    return toInstant(value).toLocaleString();
+  } catch {
+    return value;
+  }
+}

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

@@ -0,0 +1,177 @@
+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"],
+    async *stream() {},
+    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/__tests__/use-disclosure.test.tsx

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { act, renderHook } from "@testing-library/react";
+import { useDisclosure } from "../use-disclosure";
+
+describe("useDisclosure", () => {
+  test("open/close/toggle steuern den Zustand", () => {
+    const { result } = renderHook(() => useDisclosure());
+    expect(result.current.open).toBe(false);
+    act(() => result.current.onOpen());
+    expect(result.current.open).toBe(true);
+    act(() => result.current.onClose());
+    expect(result.current.open).toBe(false);
+    act(() => result.current.onToggle());
+    expect(result.current.open).toBe(true);
+  });
+
+  test("Callbacks sind referenz-stabil über Re-Renders", () => {
+    const { result, rerender } = renderHook(() => useDisclosure(true));
+    const first = result.current;
+    rerender();
+    expect(result.current.onOpen).toBe(first.onOpen);
+    expect(result.current.onClose).toBe(first.onClose);
+    expect(result.current.onToggle).toBe(first.onToggle);
+  });
+});

package/src/hooks/__tests__/use-mutation.test.tsx

@@ -0,0 +1,77 @@
+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 { useMutation } from "../use-mutation";
+
+function makeDispatcher(write: Dispatcher["write"]): Dispatcher {
+  return {
+    write,
+    query: (async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"],
+    batch: (async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"],
+    statusStore: {
+      getState: () => "online",
+      subscribe: () => () => {},
+    } as unknown as Dispatcher["statusStore"],
+    async *stream() {},
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+function wrapperFor(dispatcher: Dispatcher) {
+  return ({ children }: { readonly children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useMutation", () => {
+  test("Success setzt data, pending toggelt, Result wird durchgereicht", async () => {
+    let resolve: (() => void) | undefined;
+    const gate = new Promise<void>((r) => {
+      resolve = r;
+    });
+    const dispatcher = makeDispatcher((async (_type: string, payload: unknown) => {
+      await gate;
+      return { isSuccess: true, data: { echoed: payload } };
+    }) as unknown as Dispatcher["write"]);
+
+    const { result } = renderHook(() => useMutation<{ echoed: unknown }>("f:write:x:create"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    expect(result.current.pending).toBe(false);
+    let outcome: Awaited<ReturnType<typeof result.current.mutate>> | undefined;
+    act(() => {
+      void result.current.mutate({ name: "a" }).then((r) => {
+        outcome = r;
+      });
+    });
+    await waitFor(() => expect(result.current.pending).toBe(true));
+    act(() => resolve?.());
+    await waitFor(() => expect(result.current.pending).toBe(false));
+    expect(result.current.data).toEqual({ echoed: { name: "a" } });
+    expect(result.current.error).toBeNull();
+    expect(outcome?.isSuccess).toBe(true);
+  });
+
+  test("Failure setzt error, reset räumt auf", async () => {
+    const dispatcher = makeDispatcher((async () => ({
+      isSuccess: false,
+      error: { code: "conflict", message: "boom", i18nKey: "errors.conflict" },
+    })) as unknown as Dispatcher["write"]);
+
+    const { result } = renderHook(() => useMutation("f:write:x:create"), {
+      wrapper: wrapperFor(dispatcher),
+    });
+
+    await act(async () => {
+      await result.current.mutate({});
+    });
+    expect(result.current.error?.code).toBe("conflict");
+    act(() => result.current.reset());
+    expect(result.current.error).toBeNull();
+    expect(result.current.data).toBeNull();
+  });
+});