@cosmicdrift/kumiko-renderer 0.327.0 → 0.328.1

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

@@ -1,172 +0,0 @@
-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();
-        // skip: empty text, state already reset above
-        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-disclosure.ts

@@ -1,20 +0,0 @@
-import { useCallback, useState } from "react";
-
-// Open/close state for dialogs, sheets and collapsibles — the standard
-// replacement for the hand-rolled `useState(false)` + toggle-callback
-// trio in app screens. All callbacks are referentially stable.
-
-export type UseDisclosureResult = {
-  readonly open: boolean;
-  readonly onOpen: () => void;
-  readonly onClose: () => void;
-  readonly onToggle: () => void;
-};
-
-export function useDisclosure(initialOpen = false): UseDisclosureResult {
-  const [open, setOpen] = useState(initialOpen);
-  const onOpen = useCallback(() => setOpen(true), []);
-  const onClose = useCallback(() => setOpen(false), []);
-  const onToggle = useCallback(() => setOpen((prev) => !prev), []);
-  return { open, onOpen, onClose, onToggle };
-}

package/src/hooks/use-form.ts

@@ -1,78 +0,0 @@
-import type {
-  FormController,
-  FormControllerOptions,
-  FormSnapshot,
-  FormValues,
-} from "@cosmicdrift/kumiko-headless";
-import { createFormController } from "@cosmicdrift/kumiko-headless";
-import { useMemo, useSyncExternalStore } from "react";
-import { useOptionalDispatcher } 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> = FormControllerOptions<
-  TValues,
-  TCtx
->;
-
-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> {
-  // Optional: a form with no `submit` config (or one with an explicit
-  // dispatcher) never needs the ambient one, and mounting without a
-  // DispatcherProvider must not crash just because useForm was called.
-  const contextDispatcher = useOptionalDispatcher();
-
-  // 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 submit.dispatcher to the ambient one when omitted.
-    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

@@ -1,171 +0,0 @@
-// 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")
-//   <screenId>.f.<field> — Faceted-Filter: comma-joined selected values
-//
-// 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;
-  /** Aktive Faceted-Filter: field → ausgewählte Werte (Strings; Caller
-   *  coerced pro Field-Type). Leer wenn kein Filter gesetzt. */
-  readonly filters: Readonly<Record<string, readonly string[]>>;
-};
-
-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;
-  /** Setzt die ausgewählten Werte eines Facet-Felds. Leeres Array löscht
-   *  den Key. Resettet die Page (wie sort/search). */
-  readonly setFilter: (field: string, values: readonly string[]) => void;
-  /** Löscht alle aktiven Faceted-Filter (Reset-Button). */
-  readonly clearFilters: () => void;
-  /** Sets both bounds of a dateRange facet in ONE params update — two
-   *  setFilter calls would overwrite each other, since the second still sees
-   *  the old searchParams. An empty string clears that bound. Resets the page
-   *  like setFilter. */
-  readonly setDateRange: (
-    field: string,
-    next: { readonly from: string; readonly to: string },
-  ) => 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 filterPrefix = `${screenId}.f.`;
-  const filters = useMemo<Readonly<Record<string, readonly string[]>>>(() => {
-    const out: Record<string, readonly string[]> = {};
-    for (const [k, v] of Object.entries(params)) {
-      if (!k.startsWith(filterPrefix) || v === "") continue;
-      const field = k.slice(filterPrefix.length);
-      if (field === "") continue;
-      // ponytail: comma-join — Facet-Werte sind select-Options/booleans
-      // ohne Komma; upgrade auf repeated-keys falls je Komma-Werte nötig.
-      out[field] = v.split(",").filter((s) => s !== "");
-    }
-    return out;
-  }, [params, filterPrefix]);
-
-  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],
-  );
-
-  const setFilter = useCallback(
-    (field: string, values: readonly string[]) => {
-      nav.setSearchParams({
-        [key(screenId, `f.${field}`)]: values.length === 0 ? null : values.join(","),
-        [key(screenId, "page")]: null,
-      });
-    },
-    [nav, screenId],
-  );
-
-  const setDateRange = useCallback(
-    (field: string, next: { readonly from: string; readonly to: string }) => {
-      nav.setSearchParams({
-        [key(screenId, `f.${field}.from`)]: next.from === "" ? null : next.from,
-        [key(screenId, `f.${field}.to`)]: next.to === "" ? null : next.to,
-        [key(screenId, "page")]: null,
-      });
-    },
-    [nav, screenId],
-  );
-
-  const clearFilters = useCallback(() => {
-    const updates: Record<string, string | null> = { [key(screenId, "page")]: null };
-    for (const field of Object.keys(filters)) updates[key(screenId, `f.${field}`)] = null;
-    nav.setSearchParams(updates);
-  }, [nav, screenId, filters]);
-
-  return { sort, q, page, filters, setSort, setQ, setPage, setFilter, clearFilters, setDateRange };
-}

package/src/hooks/use-mutation.ts

@@ -1,61 +0,0 @@
-import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
-import { useCallback, useRef, useState } from "react";
-import { useDispatcher } from "../context/dispatcher-context";
-
-// React wrapper around dispatcher.write — the write-side sibling of
-// useQuery. One hook instance per handler-type; `mutate` carries the
-// payload so a single instance serves list-row actions with varying
-// payloads.
-//
-// `mutate` resolves with the raw WriteResult so callers can branch
-// (navigate on success, keep the form open on failure) without waiting
-// for a re-render of `error`/`data`.
-
-export type UseMutationResult<TData> = {
-  readonly mutate: (payload: unknown) => Promise<WriteResult<TData>>;
-  readonly pending: boolean;
-  readonly error: DispatcherError | null;
-  readonly data: TData | null;
-  readonly reset: () => void;
-};
-
-export function useMutation<TData = unknown>(type: string): UseMutationResult<TData> {
-  const dispatcher = useDispatcher();
-  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 (callSeq === sequence.current) {
-        if (result.isSuccess) {
-          setData(result.data);
-        } else {
-          setError(result.error);
-        }
-        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);
-  }, []);
-
-  return { mutate, pending, error, data, reset };
-}

package/src/hooks/use-query.ts

@@ -1,132 +0,0 @@
-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.
-export 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 });
-    // skip: a newer fetch already superseded this one, don't clobber its state
-    if (ctrl.signal.aborted) return;
-    if (result.isSuccess) {
-      setData(result.data);
-      setError(null);
-    } else {
-      // A cancelled request comes back with code "aborted" from the
-      // skip: aborted request, a newer run already replaces this result
-      if (result.error.code === "aborted") return;
-      setError(result.error);
-    }
-    setLoading(false);
-  }, [dispatcher, type, payloadKey]);
-
-  useEffect(() => {
-    if (!enabled) {
-      setLoading(false);
-      // skip: query disabled, loading state already cleared above
-      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(() => {
-    // skip: live mode or query disabled, no SSE subscription needed
-    if (!live || !enabled) return;
-    const entity = entityFromQueryType(type);
-    // skip: query type has no mapped entity, nothing to subscribe to
-    if (entity === undefined) return;
-    return subscribeLive(entity, () => {
-      void run();
-    });
-  }, [live, enabled, type, run, subscribeLive]);
-
-  return { data, error, loading, refetch: run };
-}