@cosmicdrift/kumiko-renderer-web 0.1.0

package/src/__tests__/test-utils.tsx

@@ -0,0 +1,144 @@
+// Test-Utilities für renderer-web-Tests. Wrappt `render()` mit den
+// Providern die Consumer-Komponenten (RenderEdit, RenderList,
+// KumikoScreen) zur Laufzeit erwarten: PrimitivesProvider mit den
+// HTML-Defaults, NavProvider mit einem Stub (route=undefined), und
+// LiveEventsProvider mit einem No-op-Subscriber.
+//
+// Dispatcher wird NICHT automatisch gestellt — Tests die einen
+// brauchen, mounten DispatcherProvider selber (sonst landeten alle
+// Tests mit dem gleichen Stub-Dispatcher, was echte Tests unsichtbar
+// vor-defaultet). Für Nav brauchen die kumiko-screen-Tests nur dass
+// `useNav()` nicht throwt; ein Stub reicht.
+//
+// Tests die ein anderes Setup brauchen (z.B. custom primitives, echte
+// browser-Nav) bauen ihren Wrapper selbst — siehe nav.test.tsx.
+
+import {
+  createStore,
+  type Dispatcher,
+  type DispatcherStatus,
+  type WritableStore,
+} from "@cosmicdrift/kumiko-headless";
+import {
+  createStaticLocaleResolver,
+  kumikoDefaultTranslations,
+  type LiveEventSubscriber,
+  LiveEventsProvider,
+  LocaleProvider,
+  type NavApi,
+  NavProvider,
+  PrimitivesProvider,
+  TokensProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { render as _render, type RenderOptions, type RenderResult } from "@testing-library/react";
+import type { ReactElement, ReactNode } from "react";
+import { defaultPrimitives } from "../primitives";
+import { defaultTokens } from "../tokens";
+
+// jsdom hat keinen ResizeObserver — cmdk (Combobox-Library) braucht
+// das im Setup. Stub reicht für unsere Tests; wir messen keine
+// Sizes, nur Mount-Lifecycle. Setze als globaler Side-Effect beim
+// Modul-Import damit alle Tests die test-utils laden ihn haben.
+if (typeof globalThis.ResizeObserver === "undefined") {
+  globalThis.ResizeObserver = class {
+    observe(): void {}
+    unobserve(): void {}
+    disconnect(): void {}
+  } as unknown as typeof ResizeObserver;
+}
+
+const stubNav: NavApi = {
+  route: undefined,
+  navigate: () => {},
+  replace: () => {},
+  hrefFor: (target) =>
+    target.entityId !== undefined
+      ? `/${target.screenId}/${target.entityId}`
+      : `/${target.screenId}`,
+  searchParams: {},
+  setSearchParams: () => {},
+};
+
+const stubLiveEvents: LiveEventSubscriber = () => () => {};
+
+// Stub-Tokens-API für Tests. Mode-Setter ist ein no-op — Tests die
+// Theme-Toggle testen wollen, bauen sich ihren eigenen Wrapper.
+const stubTokens = {
+  tokens: defaultTokens,
+  mode: "dark" as const,
+  setMode: () => {},
+  toggleMode: () => {},
+};
+
+const stubResolver = createStaticLocaleResolver();
+
+function DefaultProviders({ children }: { readonly children: ReactNode }): ReactNode {
+  return (
+    <TokensProvider value={stubTokens}>
+      <LocaleProvider resolver={stubResolver} fallbackBundles={[kumikoDefaultTranslations]}>
+        <PrimitivesProvider value={defaultPrimitives}>
+          <NavProvider value={stubNav}>
+            <LiveEventsProvider value={stubLiveEvents}>{children}</LiveEventsProvider>
+          </NavProvider>
+        </PrimitivesProvider>
+      </LocaleProvider>
+    </TokensProvider>
+  );
+}
+
+export function render(ui: ReactElement, options?: Omit<RenderOptions, "wrapper">): RenderResult {
+  return _render(ui, { wrapper: DefaultProviders, ...options });
+}
+
+// ---------------------------------------------------------------------------
+// Mock-Dispatcher-Helper
+// ---------------------------------------------------------------------------
+
+export type MockDispatcherOptions = {
+  /** Initialer Status. Default: "online". Tests die Transitions prüfen,
+   *  greifen den zurückgegebenen `statusStore` ab und mutieren ihn via
+   *  `statusStore.setState(...)`. */
+  readonly initialStatus?: DispatcherStatus;
+  /** Override write(). Default: returnt `{ isSuccess: true, data: {} }`. */
+  readonly write?: Dispatcher["write"];
+  /** Override query(). Default: returnt `{ isSuccess: true, data: {} }`. */
+  readonly query?: Dispatcher["query"];
+  /** Override batch(). Default: returnt `{ isSuccess: true, results: [] }`. */
+  readonly batch?: Dispatcher["batch"];
+};
+
+/** Minimal Mock-Dispatcher für renderer-web-Tests. Replaces the
+ *  hand-rolled `makeDispatcher()` Funktionen, die in fast jedem
+ *  Test-File identisch waren. Der zurückgegebene `statusStore` ist
+ *  ein WritableStore, damit Tests Status-Wechsel auslösen können —
+ *  beim public Dispatcher-Contract ist statusStore read-only, aber
+ *  Mocks dürfen mehr.
+ *
+ *  Pending queues sind immer `[]` (live-dispatcher-Semantik); Tests
+ *  die savable-Pending-Verhalten prüfen wollen, mocken den Dispatcher
+ *  selbst.
+ */
+export function createMockDispatcher(options: MockDispatcherOptions = {}): Dispatcher & {
+  /** Schreibbarer Zugriff auf den Status-Store für Test-Mutationen.
+   *  Identisch zu `dispatcher.statusStore` (Aliasing), aber als
+   *  WritableStore typisiert. */
+  readonly statusStore: WritableStore<DispatcherStatus>;
+} {
+  const statusStore = createStore<DispatcherStatus>(options.initialStatus ?? "online");
+  return {
+    write:
+      options.write ??
+      ((async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["write"]),
+    query:
+      options.query ??
+      ((async () => ({ isSuccess: true, data: {} })) as unknown as Dispatcher["query"]),
+    batch:
+      options.batch ??
+      ((async () => ({ isSuccess: true, results: [] })) as unknown as Dispatcher["batch"]),
+    statusStore,
+    pendingWrites: () => [],
+    pendingFiles: () => [],
+  };
+}
+
+export * from "@testing-library/react";

package/src/__tests__/theme-toggle.test.tsx

@@ -0,0 +1,101 @@
+// @vitest-environment jsdom
+//
+// Tests pinnen den ThemeToggle-Vertrag: Click ruft toggleMode, Icon-
+// Slot defaultet auf Unicode, Custom-Slots werden durchgereicht, das
+// title/aria-label-Paar reagiert auf den aktuellen Mode.
+//
+// Ein Stub-TokensApi reicht — der Hook useTokenController liest nur
+// `mode` + `toggleMode`, der Rest (tokens, setMode) wird vom Toggle
+// nicht angefasst.
+
+import { TokensProvider } from "@cosmicdrift/kumiko-renderer";
+import { fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { describe, expect, test, vi } from "vitest";
+import { ThemeToggle } from "../layout/theme-toggle";
+
+type StubApi = {
+  mode: "light" | "dark";
+  toggleMode: () => void;
+};
+
+function makeStub(
+  initial: "light" | "dark" = "light",
+): StubApi & { toggleMode: ReturnType<typeof vi.fn> } {
+  const stub = {
+    mode: initial,
+    toggleMode: vi.fn(),
+  } as StubApi & { toggleMode: ReturnType<typeof vi.fn> };
+  return stub;
+}
+
+function renderWithMode(stub: StubApi, ui: ReactNode) {
+  // Cast über unknown — TokensApi hat tokens/setMode die wir hier nicht
+  // brauchen, aber der Provider ist generisch typisiert.
+  const api = {
+    tokens: {} as never,
+    mode: stub.mode,
+    setMode: () => {},
+    toggleMode: stub.toggleMode,
+  };
+  return render(<TokensProvider value={api}>{ui}</TokensProvider>);
+}
+
+describe("ThemeToggle", () => {
+  test("rendert Default-Unicode-Icon (☾) im light-Mode", () => {
+    const stub = makeStub("light");
+    renderWithMode(stub, <ThemeToggle testId="t" />);
+    const btn = screen.getByTestId("t");
+    expect(btn.textContent).toContain("☾");
+    expect(btn.textContent).not.toContain("☀");
+  });
+
+  test("rendert Default-Unicode-Icon (☀) im dark-Mode", () => {
+    const stub = makeStub("dark");
+    renderWithMode(stub, <ThemeToggle testId="t" />);
+    const btn = screen.getByTestId("t");
+    expect(btn.textContent).toContain("☀");
+    expect(btn.textContent).not.toContain("☾");
+  });
+
+  test("Custom-Icons werden durchgereicht (Icon-Slots überschreiben Defaults)", () => {
+    const stub = makeStub("light");
+    renderWithMode(
+      stub,
+      <ThemeToggle
+        testId="t"
+        lightIcon={<span data-testid="light-svg">L</span>}
+        darkIcon={<span data-testid="dark-svg">D</span>}
+      />,
+    );
+    // light-mode → zeigt darkIcon (klick wechselt zu dark)
+    expect(screen.queryByTestId("dark-svg")).not.toBeNull();
+    expect(screen.queryByTestId("light-svg")).toBeNull();
+  });
+
+  test("Click ruft toggleMode genau einmal", () => {
+    const stub = makeStub("light");
+    renderWithMode(stub, <ThemeToggle testId="t" />);
+    fireEvent.click(screen.getByTestId("t"));
+    expect(stub.toggleMode).toHaveBeenCalledTimes(1);
+  });
+
+  test("aria-label und title spiegeln den Mode-Übergang", () => {
+    const lightStub = makeStub("light");
+    const { unmount } = renderWithMode(
+      lightStub,
+      <ThemeToggle testId="t" titleInLight="zu dark" titleInDark="zu light" />,
+    );
+    // Im light-Mode kündigt der Toggle an "wechselt zu dark"
+    expect(screen.getByTestId("t").getAttribute("aria-label")).toBe("zu dark");
+    expect(screen.getByTestId("t").getAttribute("title")).toBe("zu dark");
+    unmount();
+
+    const darkStub = makeStub("dark");
+    renderWithMode(
+      darkStub,
+      <ThemeToggle testId="t" titleInLight="zu dark" titleInDark="zu light" />,
+    );
+    expect(screen.getByTestId("t").getAttribute("aria-label")).toBe("zu light");
+  });
+});

package/src/__tests__/toast.test.tsx

@@ -0,0 +1,162 @@
+// @vitest-environment jsdom
+//
+// ToastProvider + useToast pinnt: toast() rendert Title+Description in
+// einem Radix-Toast; mehrere toasts stapeln; Variant=destructive setzt
+// die destructive-Klasse; useToast außerhalb des Providers ist no-op
+// (kein crash); IDs sind kollisionsfrei auch bei zwei Calls im selben
+// Tick (Counter-Race-Bug).
+
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import { type ReactNode, useEffect } from "react";
+import { describe, expect, test } from "vitest";
+import { type ToastOptions, ToastProvider, useToast } from "../primitives/toast";
+
+// Trigger-Component die im Mount toast() aufruft. So testen wir den
+// Hook ohne userEvent-Klick-Pfad und ohne fragile timer.
+function ToastTrigger({ options }: { readonly options: readonly ToastOptions[] }): ReactNode {
+  const { toast } = useToast();
+  useEffect(() => {
+    for (const o of options) toast(o);
+    // toast() ist in der ToastApi memoized — keine Re-Trigger-Loops.
+  }, [toast, options]);
+  return null;
+}
+
+describe("ToastProvider + useToast", () => {
+  test("toast() pushed Title und Description in den Viewport", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger options={[{ title: "Saved", description: "Changes applied" }]} />
+      </ToastProvider>,
+    );
+    expect(screen.getByText("Saved")).toBeTruthy();
+    expect(screen.getByText("Changes applied")).toBeTruthy();
+  });
+
+  test("toast() ohne description rendert nur den Title", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger options={[{ title: "Copied" }]} />
+      </ToastProvider>,
+    );
+    expect(screen.getByText("Copied")).toBeTruthy();
+  });
+
+  test("docsUrl: rendert 'Mehr erfahren →' Link mit target=_blank", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger
+          options={[
+            {
+              title: "Konflikt",
+              variant: "destructive",
+              docsUrl: "https://docs.kumiko.so/errors/stale_state",
+            },
+          ]}
+        />
+      </ToastProvider>,
+    );
+    const link = screen.getByRole("link", { name: /Mehr erfahren/i });
+    expect(link.getAttribute("href")).toBe("https://docs.kumiko.so/errors/stale_state");
+    expect(link.getAttribute("target")).toBe("_blank");
+    expect(link.getAttribute("rel")).toBe("noopener noreferrer");
+  });
+
+  test("docsLinkLabel override: nutzt vom Caller gegebenen Text", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger
+          options={[
+            {
+              title: "Conflict",
+              docsUrl: "https://docs.kumiko.so/errors/stale_state",
+              docsLinkLabel: "Learn more",
+            },
+          ]}
+        />
+      </ToastProvider>,
+    );
+    expect(screen.getByRole("link", { name: /Learn more/i })).toBeTruthy();
+  });
+
+  test("ohne docsUrl: kein Link gerendert", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger options={[{ title: "Saved", description: "ok" }]} />
+      </ToastProvider>,
+    );
+    expect(screen.queryByRole("link")).toBeNull();
+  });
+
+  test("variant=destructive: setzt die destructive-Klasse auf den Root", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger options={[{ title: "Failed", variant: "destructive" }]} />
+      </ToastProvider>,
+    );
+    // Class-Mapping ist der Public-Vertrag mit Tailwind-Tokens. Wir
+    // suchen den nearest Ancestor des Title-Knotens dessen Klassen-
+    // String "destructive" enthält — Radix-Toast.Root rendert in einem
+    // <li>, aber die genaue Role wechselt je nach priority/type.
+    let node: HTMLElement | null = screen.getByText("Failed");
+    while (node !== null && !node.className.includes("destructive")) {
+      node = node.parentElement;
+    }
+    expect(node).not.toBeNull();
+  });
+
+  test("zwei toasts: beide Entries sind im DOM (Stacking)", () => {
+    render(
+      <ToastProvider>
+        <ToastTrigger options={[{ title: "First" }, { title: "Second" }]} />
+      </ToastProvider>,
+    );
+    expect(screen.getByText("First")).toBeTruthy();
+    expect(screen.getByText("Second")).toBeTruthy();
+  });
+
+  test("zwei toasts im selben Tick: getrennte React-keys (Counter-Race-Regression)", () => {
+    // Vorher hatte ToastProvider einen useState-counter, der wegen
+    // Closure-Capture bei Doppel-Calls denselben Wert sah → identische
+    // IDs → React-key-Kollision (Warning + UI-Glitch). Der Fix nutzt
+    // useRef. Test: zwei toasts + console.error darf kein "duplicate
+    // key" loggen.
+    const errors: string[] = [];
+    /* biome-ignore lint/suspicious/noConsole: test spy auf React's duplicate-key-Warning, die nur über console.error gemeldet wird */
+    const original = console.error;
+    console.error = (...args: unknown[]): void => {
+      errors.push(args.map(String).join(" "));
+    };
+    try {
+      render(
+        <ToastProvider>
+          <ToastTrigger options={[{ title: "A" }, { title: "B" }]} />
+        </ToastProvider>,
+      );
+      const dup = errors.filter((e) => /duplicate key|Encountered two children/i.test(e));
+      expect(dup).toEqual([]);
+    } finally {
+      console.error = original;
+    }
+  });
+
+  test("useToast außerhalb des Providers: no-op, kein Crash", () => {
+    // Component die useToast nutzt aber NICHT in <ToastProvider> mounted
+    // ist — z.B. ein Test ohne Provider, oder ein Pre-Mount-Code-Path.
+    // Soll ohne Throw rendern.
+    function Outside(): ReactNode {
+      const { toast } = useToast();
+      return (
+        <button type="button" onClick={() => toast({ title: "Stub" })}>
+          trigger
+        </button>
+      );
+    }
+    render(<Outside />);
+    // Click feuert toast() — sollte einfach durchlaufen ohne Effekt.
+    act(() => {
+      fireEvent.click(screen.getByRole("button"));
+    });
+    expect(screen.queryByText("Stub")).toBeNull();
+  });
+});

package/src/__tests__/use-form.test.tsx

@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import { DispatcherProvider, useForm } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { describe, expect, test, vi } from "vitest";
+import { z } from "zod";
+import { act, createMockDispatcher, renderHook } from "./test-utils";
+
+type Values = { title: string; count?: number };
+
+function makeDispatcher(writeFn?: Dispatcher["write"]): Dispatcher {
+  return createMockDispatcher({ write: writeFn });
+}
+
+function wrap(dispatcher: Dispatcher) {
+  return ({ children }: { children: ReactNode }) => (
+    <DispatcherProvider dispatcher={dispatcher}>{children}</DispatcherProvider>
+  );
+}
+
+describe("useForm", () => {
+  test("snapshot reflects setField mutations", () => {
+    const dispatcher = makeDispatcher();
+    const { result } = renderHook(
+      () =>
+        useForm<Values>({
+          initial: { title: "", count: 0 },
+          submit: { type: "x:create" },
+        }),
+      { wrapper: wrap(dispatcher) },
+    );
+
+    expect(result.current.snapshot.values.title).toBe("");
+    expect(result.current.snapshot.isDirty).toBe(false);
+
+    act(() => result.current.controller.setField("title", "hello"));
+    expect(result.current.snapshot.values.title).toBe("hello");
+    expect(result.current.snapshot.isDirty).toBe(true);
+    expect(result.current.snapshot.changes.title).toBe("hello");
+  });
+
+  test("submit dispatches to the context dispatcher when no explicit one is passed", async () => {
+    const write = vi.fn(async () => ({ isSuccess: true, data: { id: "123" } }) as never);
+    const dispatcher = makeDispatcher(write);
+    const { result } = renderHook(
+      () =>
+        useForm<Values>({
+          initial: { title: "", count: 0 },
+          submit: { type: "x:create" },
+        }),
+      { wrapper: wrap(dispatcher) },
+    );
+
+    act(() => result.current.controller.setField("title", "new"));
+    let submitResult: unknown;
+    await act(async () => {
+      submitResult = await result.current.controller.submit();
+    });
+
+    expect(write).toHaveBeenCalledOnce();
+    expect(write).toHaveBeenCalledWith("x:create", expect.anything());
+    expect((submitResult as { isSuccess: boolean }).isSuccess).toBe(true);
+  });
+
+  test("zod schema failure blocks submit; no network call fires", async () => {
+    const write = vi.fn();
+    const dispatcher = makeDispatcher(write as unknown as Dispatcher["write"]);
+    const schema = z.object({ title: z.string().min(1), count: z.number().optional() });
+    const { result } = renderHook(
+      () =>
+        useForm<Values>({
+          initial: { title: "", count: 0 },
+          schema,
+          submit: { type: "x:create" },
+        }),
+      { wrapper: wrap(dispatcher) },
+    );
+
+    let submitResult: unknown;
+    await act(async () => {
+      submitResult = await result.current.controller.submit();
+    });
+
+    expect(write).not.toHaveBeenCalled();
+    expect((submitResult as { validationBlocked: boolean }).validationBlocked).toBe(true);
+    expect(Object.keys(result.current.snapshot.errors)).toContain("title");
+  });
+
+  test("explicit dispatcher on submit wins over context dispatcher", async () => {
+    const contextWrite = vi.fn(async () => ({ isSuccess: true, data: {} }) as never);
+    const overrideWrite = vi.fn(async () => ({ isSuccess: true, data: {} }) as never);
+    const contextDispatcher = makeDispatcher(contextWrite);
+    const overrideDispatcher = makeDispatcher(overrideWrite);
+
+    const { result } = renderHook(
+      () =>
+        useForm<Values>({
+          initial: { title: "hi", count: 0 },
+          submit: { type: "x:create", dispatcher: overrideDispatcher },
+        }),
+      { wrapper: wrap(contextDispatcher) },
+    );
+
+    act(() => result.current.controller.setField("title", "changed"));
+    await act(async () => {
+      await result.current.controller.submit();
+    });
+
+    expect(overrideWrite).toHaveBeenCalled();
+    expect(contextWrite).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/use-query-live.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+import type { Dispatcher } from "@cosmicdrift/kumiko-headless";
+import {
+  DispatcherProvider,
+  type LiveEvent,
+  type LiveEventSubscriber,
+  LiveEventsProvider,
+  useQuery,
+} from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+import { describe, expect, test } from "vitest";
+import { act, createMockDispatcher, render, waitFor } from "./test-utils";
+
+// Test-Helper: fake LiveEventSubscriber. Sammelt alle Subscriber, das
+// Test kann `inject(type, data)` rufen um die matching listener zu
+// feuern. Ersetzt die alten `__injectLiveEvent`-Seams aus dem
+// Module-Singleton; jetzt lebt der Fake im Provider-Tree — identisch
+// zum Production-Pattern.
+function makeFakeLiveEvents(): {
+  subscriber: LiveEventSubscriber;
+  inject: (type: string, data: LiveEvent["data"]) => void;
+} {
+  const listeners = new Set<{ entity: string; cb: (e: LiveEvent) => void }>();
+  return {
+    subscriber: (entity, cb) => {
+      const entry = { entity, cb };
+      listeners.add(entry);
+      return () => {
+        listeners.delete(entry);
+      };
+    },
+    inject: (type, data) => {
+      for (const l of listeners) {
+        if (l.entity === data.aggregateType) l.cb({ type, data });
+      }
+    },
+  };
+}
+
+function makeDispatcher(queryFn: Dispatcher["query"]): Dispatcher {
+  return createMockDispatcher({ query: queryFn });
+}
+
+function Probe({ live }: { readonly live: boolean }): React.ReactElement {
+  const q = useQuery<{ count: number }>("tasks:query:task:list", {}, { live });
+  return <div data-testid="probe">{q.data?.count ?? "loading"}</div>;
+}
+
+function Wrapper({
+  children,
+  dispatcher,
+  liveEvents,
+}: {
+  readonly children: ReactNode;
+  readonly dispatcher: Dispatcher;
+  readonly liveEvents: LiveEventSubscriber;
+}): ReactNode {
+  return (
+    <DispatcherProvider dispatcher={dispatcher}>
+      <LiveEventsProvider value={liveEvents}>{children}</LiveEventsProvider>
+    </DispatcherProvider>
+  );
+}
+
+describe("useQuery live-mode", () => {
+  test("live=true: injected event triggert refetch", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async () => {
+      calls += 1;
+      return { isSuccess: true, data: { count: calls } };
+    }) as unknown as Dispatcher["query"]);
+    const fake = makeFakeLiveEvents();
+
+    const { getByTestId } = render(
+      <Wrapper dispatcher={dispatcher} liveEvents={fake.subscriber}>
+        <Probe live={true} />
+      </Wrapper>,
+    );
+
+    await waitFor(() => expect(getByTestId("probe").textContent).toBe("1"));
+
+    act(() => {
+      fake.inject("task.created", {
+        id: "t1",
+        aggregateType: "task",
+        version: 1,
+        payload: {},
+        createdAt: "",
+      });
+    });
+
+    await waitFor(() => expect(getByTestId("probe").textContent).toBe("2"));
+  });
+
+  test("live=false: injected event wird ignoriert, kein refetch", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async () => {
+      calls += 1;
+      return { isSuccess: true, data: { count: calls } };
+    }) as unknown as Dispatcher["query"]);
+    const fake = makeFakeLiveEvents();
+
+    const { getByTestId } = render(
+      <Wrapper dispatcher={dispatcher} liveEvents={fake.subscriber}>
+        <Probe live={false} />
+      </Wrapper>,
+    );
+
+    await waitFor(() => expect(getByTestId("probe").textContent).toBe("1"));
+
+    fake.inject("task.created", {
+      id: "t1",
+      aggregateType: "task",
+      version: 1,
+      payload: {},
+      createdAt: "",
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(getByTestId("probe").textContent).toBe("1");
+    expect(calls).toBe(1);
+  });
+
+  test("live=true: nur events für die Query-Entity triggern refetch", async () => {
+    let calls = 0;
+    const dispatcher = makeDispatcher((async () => {
+      calls += 1;
+      return { isSuccess: true, data: { count: calls } };
+    }) as unknown as Dispatcher["query"]);
+    const fake = makeFakeLiveEvents();
+
+    const { getByTestId } = render(
+      <Wrapper dispatcher={dispatcher} liveEvents={fake.subscriber}>
+        <Probe live={true} />
+      </Wrapper>,
+    );
+
+    await waitFor(() => expect(getByTestId("probe").textContent).toBe("1"));
+
+    // Event für andere Entity — kein refetch.
+    fake.inject("note.created", {
+      id: "n1",
+      aggregateType: "note",
+      version: 1,
+      payload: {},
+      createdAt: "",
+    });
+
+    await new Promise((r) => setTimeout(r, 50));
+    expect(calls).toBe(1);
+  });
+});