@cosmicdrift/kumiko-renderer 0.327.0 → 0.328.1

package/{src/format-when.ts → dist/format-when.js}

@@ -1,11 +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;
-  }
+export function formatWhen(value) {
+    try {
+        return toInstant(value).toLocaleString();
+    }
+    catch {
+        return value;
+    }
 }

package/dist/hooks/reference-limits.d.ts

@@ -0,0 +1,3 @@
+export declare const REFERENCE_COMBOBOX_LIMIT = 50;
+export declare const REFERENCE_LIST_LOOKUP_LIMIT = 200;
+export declare const REFERENCE_SEARCH_DEBOUNCE_MS = 300;

package/{src/hooks/reference-limits.ts → dist/hooks/reference-limits.js}

@@ -12,7 +12,6 @@
 // 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/dist/hooks/use-ai-text.d.ts

@@ -0,0 +1,52 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+export declare 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;
+};
+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;
+};
+export declare function useAiTextAction(): UseAiTextActionResult;
+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;
+};
+export declare function useCompletion(debounceMs?: number): UseCompletionResult;

package/dist/hooks/use-ai-text.js

@@ -0,0 +1,90 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context.js";
+// 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";
+function stateForError(error) {
+    if (error.code === "cap_exceeded" || error.code === "rate_limited")
+        return "cap-exceeded";
+    if (error.code === "feature_disabled")
+        return "unavailable";
+    return "error";
+}
+export function useAiTextAction() {
+    const dispatcher = useDispatcher();
+    const [state, setState] = useState("idle");
+    const [result, setResult] = useState(null);
+    const [error, setError] = useState(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(null);
+    useEffect(() => {
+        return () => {
+            activeCtrl.current?.abort();
+        };
+    }, []);
+    const run = useCallback(async (payload) => {
+        activeCtrl.current?.abort();
+        const ctrl = new AbortController();
+        activeCtrl.current = ctrl;
+        setState("loading");
+        setError(null);
+        const res = await dispatcher.query(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 };
+}
+const DEFAULT_DEBOUNCE_MS = 500;
+export function useCompletion(debounceMs = DEFAULT_DEBOUNCE_MS) {
+    const { run, state, result, error, reset } = useAiTextAction();
+    const timerRef = useRef(undefined);
+    const clearTimer = useCallback(() => {
+        if (timerRef.current !== undefined) {
+            clearTimeout(timerRef.current);
+            timerRef.current = undefined;
+        }
+    }, []);
+    const requestCompletion = useCallback((text) => {
+        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/dist/hooks/use-disclosure.d.ts

@@ -0,0 +1,7 @@
+export type UseDisclosureResult = {
+    readonly open: boolean;
+    readonly onOpen: () => void;
+    readonly onClose: () => void;
+    readonly onToggle: () => void;
+};
+export declare function useDisclosure(initialOpen?: boolean): UseDisclosureResult;

package/dist/hooks/use-disclosure.js

@@ -0,0 +1,8 @@
+import { useCallback, useState } from "react";
+export function useDisclosure(initialOpen = false) {
+    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/dist/hooks/use-form.d.ts

@@ -0,0 +1,7 @@
+import type { FormController, FormControllerOptions, FormSnapshot, FormValues } from "@cosmicdrift/kumiko-headless";
+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 declare function useForm<TValues extends FormValues, TCtx = unknown>(options: UseFormOptions<TValues, TCtx>): UseFormResult<TValues>;

package/dist/hooks/use-form.js

@@ -0,0 +1,36 @@
+import { createFormController } from "@cosmicdrift/kumiko-headless";
+import { useMemo, useSyncExternalStore } from "react";
+import { useOptionalDispatcher } from "../context/dispatcher-context.js";
+export function useForm(options) {
+    // 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(() => {
+        const rawSubmit = options.submit;
+        const submitConfig = rawSubmit
+            ? { ...rawSubmit, dispatcher: rawSubmit.dispatcher ?? contextDispatcher }
+            : undefined;
+        const controllerOptions = {
+            ...options,
+            ...(submitConfig !== undefined && { submit: submitConfig }),
+        };
+        return createFormController(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/dist/hooks/use-list-url-state.d.ts

@@ -0,0 +1,43 @@
+import type { DataTableSort, DataTableSortDir } from "../primitives.js";
+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;
+    /** User-chosen page size from `PAGE_SIZE_OPTIONS`; undefined = screen default. */
+    readonly pageSize: number | undefined;
+    /** 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;
+    /** Sets the page size and resets the page; undefined clears the key. */
+    readonly setPageSize: (next: number | undefined) => 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;
+};
+export declare const PAGE_SIZE_OPTIONS: readonly number[];
+export declare function useListUrlState(screenId: string): ListUrlStateApi;

package/dist/hooks/use-list-url-state.js

@@ -0,0 +1,131 @@
+// 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.js";
+// `.` 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.
+export const PAGE_SIZE_OPTIONS = [25, 50, 100];
+function parsePageSize(value) {
+    if (value === undefined)
+        return undefined;
+    const n = Number.parseInt(value, 10);
+    return PAGE_SIZE_OPTIONS.includes(n) ? n : undefined;
+}
+function key(screenId, suffix) {
+    return `${screenId}.${suffix}`;
+}
+function parseDir(value) {
+    return value === "asc" || value === "desc" ? value : undefined;
+}
+function parsePage(value) {
+    if (value === undefined)
+        return 1;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) && n > 0 ? n : 1;
+}
+export function useListUrlState(screenId) {
+    const nav = useNav();
+    const params = nav.searchParams;
+    const sort = useMemo(() => {
+        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 pageSize = parsePageSize(params[key(screenId, "size")]);
+    const filterPrefix = `${screenId}.f.`;
+    const filters = useMemo(() => {
+        const out = {};
+        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) => {
+        // 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) => {
+        // 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) => {
+        nav.setSearchParams({
+            [key(screenId, "page")]: next <= 1 ? null : String(next),
+        });
+    }, [nav, screenId]);
+    const setPageSize = useCallback((next) => {
+        nav.setSearchParams({
+            [key(screenId, "size")]: next === undefined ? null : String(next),
+            [key(screenId, "page")]: null,
+        });
+    }, [nav, screenId]);
+    const setFilter = useCallback((field, values) => {
+        nav.setSearchParams({
+            [key(screenId, `f.${field}`)]: values.length === 0 ? null : values.join(","),
+            [key(screenId, "page")]: null,
+        });
+    }, [nav, screenId]);
+    const setDateRange = useCallback((field, next) => {
+        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 = { [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,
+        pageSize,
+        filters,
+        setSort,
+        setQ,
+        setPage,
+        setPageSize,
+        setFilter,
+        clearFilters,
+        setDateRange,
+    };
+}

package/dist/hooks/use-mutation.d.ts

@@ -0,0 +1,9 @@
+import type { DispatcherError, WriteResult } from "@cosmicdrift/kumiko-headless";
+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 declare function useMutation<TData = unknown>(type: string): UseMutationResult<TData>;

package/dist/hooks/use-mutation.js

@@ -0,0 +1,37 @@
+import { useCallback, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context.js";
+export function useMutation(type) {
+    const dispatcher = useDispatcher();
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(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) => {
+        const callSeq = ++sequence.current;
+        setPending(true);
+        setError(null);
+        const result = await dispatcher.write(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/dist/hooks/use-query.d.ts

@@ -0,0 +1,14 @@
+import type { DispatcherError } from "@cosmicdrift/kumiko-headless";
+export type UseQueryResult<TData> = {
+    readonly data: TData | null;
+    readonly error: DispatcherError | null;
+    readonly loading: boolean;
+    readonly refetch: () => Promise<void>;
+};
+export type UseQueryOptions = {
+    readonly enabled?: boolean;
+    readonly live?: boolean;
+    readonly refetchIntervalMs?: number;
+};
+export declare function entityFromQueryType(type: string): string | undefined;
+export declare function useQuery<TData = unknown>(type: string, payload: unknown, options?: UseQueryOptions): UseQueryResult<TData>;

package/dist/hooks/use-query.js

@@ -0,0 +1,118 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatcher } from "../context/dispatcher-context.js";
+import { useLiveEvents } from "../sse/live-events.js";
+// 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) {
+    // 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(type, payload, options = {}) {
+    const dispatcher = useDispatcher();
+    const { enabled = true, live = false, refetchIntervalMs } = options;
+    const [data, setData] = useState(null);
+    const [error, setError] = useState(null);
+    const [loading, setLoading] = useState(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(null);
+    // A tick that aborted a running fetch would starve slow queries, so
+    // ticks consult this flag instead.
+    const fetchInFlight = useRef(false);
+    // 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 runFetch = useCallback(async (background) => {
+        // 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;
+        fetchInFlight.current = true;
+        if (!background)
+            setLoading(true);
+        let result;
+        try {
+            result = await dispatcher.query(type, payload, { signal: ctrl.signal });
+        }
+        finally {
+            // A rejected fetch must not leave polling stuck; a superseded one must
+            // not clear the newer fetch's flag.
+            if (activeCtrl.current === ctrl)
+                fetchInFlight.current = false;
+        }
+        // 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]);
+    const run = useCallback(() => runFetch(false), [runFetch]);
+    useEffect(() => {
+        if (!enabled) {
+            setLoading(false);
+            // skip: query disabled, loading state already cleared above
+            return;
+        }
+        void run();
+        return () => {
+            activeCtrl.current?.abort();
+            fetchInFlight.current = false;
+        };
+    }, [enabled, run]);
+    useEffect(() => {
+        // skip: polling off or disabled query
+        if (!enabled || refetchIntervalMs === undefined)
+            return;
+        // skip: non-positive or non-finite interval disables polling
+        if (!Number.isFinite(refetchIntervalMs) || refetchIntervalMs <= 0)
+            return;
+        const timer = setInterval(() => {
+            // skip: a fetch is still running, the next tick retries
+            if (fetchInFlight.current)
+                return;
+            void runFetch(true);
+        }, refetchIntervalMs);
+        return () => clearInterval(timer);
+    }, [enabled, refetchIntervalMs, runFetch]);
+    // 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 };
+}

package/dist/hooks/use-reference-lookup.d.ts

@@ -0,0 +1,14 @@
+export type ReferenceLookupMap = ReadonlyMap<string, string>;
+/** Where a reference target's label rows come from: the central override for
+ *  that `feature:entity` if one exists, else the entity-convention list
+ *  handler plus the caller's own label field. */
+export declare function referenceLookupSource(refFeature: string, refEntity: string, labelField: string): {
+    readonly queryQn: string;
+    readonly labelKey: string;
+};
+/** Empty while the query loads (or fails), so callers fall back to the raw id.
+ *  `featureName` is the reference's target feature, not the screen's. */
+export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
+    readonly map: ReferenceLookupMap;
+    readonly loading: boolean;
+};