npm - @cosmicdrift/kumiko-renderer-web - Versions diffs - 0.2.3 → 0.3.0 - Mend

@cosmicdrift/kumiko-renderer-web 0.2.3 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/CHANGELOG.md +59 -0
package/package.json +26 -23
package/src/__tests__/visual-tree-integration.test.tsx +315 -0
package/src/__tests__/workspace-shell.test.tsx +142 -0
package/src/app/client-plugin.tsx +30 -0
package/src/app/create-app.tsx +45 -5
package/src/app/resolvers-context.tsx +29 -0
package/src/app/tree-providers-context.tsx +44 -0
package/src/layout/__tests__/visual-tree.test.tsx +287 -0
package/src/layout/avatar.tsx +1 -1
package/src/layout/editor-panel.tsx +91 -0
package/src/layout/target-resolver-stub.tsx +53 -0
package/src/layout/tree-node-renderer.tsx +292 -0
package/src/layout/visual-tree.tsx +238 -0
package/src/layout/workspace-shell.tsx +31 -5

package/src/app/create-app.tsx CHANGED Viewed

@@ -1,4 +1,5 @@
 import { createLiveDispatcher } from "@cosmicdrift/kumiko-dispatcher-live";
+import type { TreeChildrenSubscribe } from "@cosmicdrift/kumiko-framework/engine";
 import type {
   Dispatcher,
   ListRowViewModel,
@@ -35,6 +36,8 @@ import { useBrowserTokensApi } from "../tokens";
 import { createBrowserLocaleResolver } from "./browser-locale";
 import { type ClientFeatureDefinition, stackWrappers } from "./client-plugin";
 import { useBrowserNavApi } from "./nav";
+import { type ResolverComponent, ResolversProvider } from "./resolvers-context";
+import { TreeProvidersProvider } from "./tree-providers-context";
 // Web-Bootstrap. Mounted den ganzen Kumiko-Render-Stack im Browser:
 // Tokens (class-based light/dark via <html>), Primitives (HTML),
@@ -192,7 +195,40 @@ export function createKumikoApp(options: CreateKumikoAppOptions = {}): void {
     }
   }
-  const resolver = options.locale ?? createBrowserLocaleResolver();
+  // Tree-Provider-Map aggregieren — keyed by clientFeature.name (matches
+  // server-side FeatureDefinition.name). Mehrere clientFeatures mit
+  // gleichem name + treeProvider sind ein Author-Bug (würde stillschweigend
+  // den Provider eines Features durch den eines anderen überschreiben);
+  // wir warnen einmal pro Kollision. Visual-Tree.md V.1.1-Distribution.
+  const treeProviders = new Map<string, TreeChildrenSubscribe>();
+  for (const f of clientFeatures) {
+    if (f.treeProvider === undefined) continue;
+    if (treeProviders.has(f.name)) {
+      // biome-ignore lint/suspicious/noConsole: dev-warning für Schema-Konflikte
+      console.warn(
+        `[kumiko] treeProvider for "${f.name}" defined by multiple clientFeatures — last definition wins.`,
+      );
+    }
+    treeProviders.set(f.name, f.treeProvider);
+  }
+  // Editor-Resolver aggregieren — keyed by "featureId:action". Gleiche
+  // Last-Wins-Semantik wie columnRenderers. Warnung bei Kollision.
+  const resolvers = new Map<string, ResolverComponent>();
+  for (const f of clientFeatures) {
+    if (f.resolvers === undefined) continue;
+    for (const [key, component] of Object.entries(f.resolvers)) {
+      if (resolvers.has(key)) {
+        // biome-ignore lint/suspicious/noConsole: client-bundle has no logger; collision is a dev-time warning that must surface in the browser DevTools.
+        console.warn(
+          `[kumiko] resolver "${key}" defined by multiple clientFeatures — last definition (from "${f.name}") wins.`,
+        );
+      }
+      resolvers.set(key, component);
+    }
+  }
+  const localeResolver = options.locale ?? createBrowserLocaleResolver();
   const navAdapter = options.navAdapter ?? useBrowserNavApi;
   const hasWorkspaces = (app.workspaces?.length ?? 0) > 0;
@@ -210,15 +246,19 @@ export function createKumikoApp(options: CreateKumikoAppOptions = {}): void {
   const tree = (
     <TokensBoot>
-      <LocaleProvider resolver={resolver} fallbackBundles={fallbackBundles}>
+      <LocaleProvider resolver={localeResolver} fallbackBundles={fallbackBundles}>
         <PrimitivesProvider value={primitives}>
           <DispatcherProvider dispatcher={dispatcher}>
             <LiveEventsProvider value={liveEvents}>
               <CustomScreensProvider value={customScreens}>
                 <ColumnRenderersProvider value={columnRenderers}>
-                  <ToastProvider>
-                    {stackWrappers(providers, stackWrappers(gates, screenNode))}
-                  </ToastProvider>
+                  <TreeProvidersProvider value={treeProviders}>
+                    <ResolversProvider resolvers={resolvers}>
+                      <ToastProvider>
+                        {stackWrappers(providers, stackWrappers(gates, screenNode))}
+                      </ToastProvider>
+                    </ResolversProvider>
+                  </TreeProvidersProvider>
                 </ColumnRenderersProvider>
               </CustomScreensProvider>
             </LiveEventsProvider>

package/src/app/resolvers-context.tsx ADDED Viewed

@@ -0,0 +1,29 @@
+// ResolversContext — stellt Editor-Resolver-Komponenten für das
+// EditorPanel bereit. Aggregiert in createKumikoApp aus allen
+// clientFeatures.resolvers, analog zu treeProviders-context.
+// Siehe visual-tree.md V.1.2.
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+import type { ComponentType, ReactNode } from "react";
+import { createContext, useContext } from "react";
+export type ResolverComponent = ComponentType<{
+  readonly target: TargetRef;
+  readonly onClose: () => void;
+}>;
+const ResolversContext = createContext<ReadonlyMap<string, ResolverComponent> | null>(null);
+export type ResolversProviderProps = {
+  readonly resolvers: ReadonlyMap<string, ResolverComponent>;
+  readonly children: ReactNode;
+};
+export function ResolversProvider({ resolvers, children }: ResolversProviderProps): ReactNode {
+  return <ResolversContext.Provider value={resolvers}>{children}</ResolversContext.Provider>;
+}
+export function useResolvers(): ReadonlyMap<string, ResolverComponent> {
+  const ctx = useContext(ResolversContext);
+  return ctx ?? new Map();
+}

package/src/app/tree-providers-context.tsx ADDED Viewed

@@ -0,0 +1,44 @@
+// TreeProvidersContext — React-Context für die client-side TreeProvider-
+// Map. Wird von createKumikoApp aus den `clientFeatures[].treeProvider`-
+// Feldern aggregiert und steht damit allen Layout-Komponenten zur
+// Verfügung (insbesondere VisualTree im WorkspaceShell).
+//
+// **Warum Context, nicht Prop**: WorkspaceShell ist bereits multi-Prop
+// (brand, schema, user, sidebarFooter, ...). Provider-Map wäre der
+// nächste Required-when-tree-mode-Prop und würde das Interface aufweichen
+// (welche Props sind Pflicht wann?). Context-Pattern ist konsistent zu
+// existing kumiko-renderer-Mechanik (NavProvider, LocaleProvider,
+// PrimitivesProvider, LiveEventsProvider) — alle für „cross-component
+// state aus app-level".
+//
+// **Default-Wert** ist eine leere Map. Apps ohne Tree-Workspace mounten
+// die App ohne `clientFeatures` mit `treeProvider`, und VisualTree
+// rendert eine empty-state-Sicht. Memory `[Sicherheit > Convenience]`:
+// kein silent-fallback, sondern explicit empty.
+//
+// Siehe visual-tree.md V.1.1-Distribution-Mechanismus.
+import type { TreeChildrenSubscribe } from "@cosmicdrift/kumiko-framework/engine";
+import { createContext, type ReactNode, useContext } from "react";
+const EMPTY_PROVIDERS: ReadonlyMap<string, TreeChildrenSubscribe> = new Map();
+const TreeProvidersContext =
+  createContext<ReadonlyMap<string, TreeChildrenSubscribe>>(EMPTY_PROVIDERS);
+export type TreeProvidersProviderProps = {
+  readonly value: ReadonlyMap<string, TreeChildrenSubscribe>;
+  readonly children: ReactNode;
+};
+export function TreeProvidersProvider({ value, children }: TreeProvidersProviderProps): ReactNode {
+  return <TreeProvidersContext.Provider value={value}>{children}</TreeProvidersContext.Provider>;
+}
+/** Hook für TreeProvider-Map-Konsumenten (VisualTree im WorkspaceShell).
+ *  Returnt eine empty Map wenn die App keine clientFeatures mit
+ *  treeProvider registriert hat — sicheres Default-Verhalten ohne
+ *  Crash. */
+export function useTreeProviders(): ReadonlyMap<string, TreeChildrenSubscribe> {
+  return useContext(TreeProvidersContext);
+}

package/src/layout/__tests__/visual-tree.test.tsx ADDED Viewed

@@ -0,0 +1,287 @@
+// @vitest-environment jsdom
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { TreeProvidersProvider } from "../../app/tree-providers-context";
+import { setDispatchListener } from "../target-resolver-stub";
+import { VisualTree } from "../visual-tree";
+// Mock-Provider-Helper. emit wird einmal initial gerufen mit den
+// gegebenen Nodes; cleanup ist no-op. Subscriptions können später
+// auch dynamisch sein (siehe `makeMutableProvider`).
+function makeStaticProvider(nodes: readonly TreeNode[]): TreeChildrenSubscribe {
+  return () => (emit) => {
+    emit(nodes);
+    return () => {};
+  };
+}
+// Mutable-Provider — Test kann via `emitFn` einen weiteren Emit
+// auslösen um Subscribe-Update zu beweisen. Returnt ein Tupel
+// [provider, controls].
+function makeMutableProvider(initial: readonly TreeNode[]): {
+  readonly provider: TreeChildrenSubscribe;
+  emit(nodes: readonly TreeNode[]): void;
+} {
+  let listener: ((nodes: readonly TreeNode[]) => void) | undefined;
+  const provider: TreeChildrenSubscribe = () => (emit) => {
+    listener = emit;
+    emit(initial);
+    return () => {
+      listener = undefined;
+    };
+  };
+  return {
+    provider,
+    emit(nodes) {
+      if (listener !== undefined) listener(nodes);
+    },
+  };
+}
+function renderTree(
+  providers: ReadonlyMap<string, TreeChildrenSubscribe>,
+): ReturnType<typeof render> {
+  function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+    return <TreeProvidersProvider value={providers}>{children}</TreeProvidersProvider>;
+  }
+  return render(<VisualTree workspaceId="test-ws" />, { wrapper: Wrapper });
+}
+// vitest+Bun-Runtime liefert nur ein partielles localStorage (kein
+// `clear`/`removeItem`). Wir installieren pro Test einen frischen
+// Map-basierten Mock, damit Standard-API-Methoden funktionieren und
+// Test-Isolation sauber ist. Production-Code nutzt nur die Standard-
+// Schnittstelle, daher transparent.
+beforeEach(() => {
+  const store = new Map<string, string>();
+  Object.defineProperty(window, "localStorage", {
+    configurable: true,
+    value: {
+      getItem: (key: string): string | null => store.get(key) ?? null,
+      setItem: (key: string, value: string): void => {
+        store.set(key, value);
+      },
+      removeItem: (key: string): void => {
+        store.delete(key);
+      },
+      clear: (): void => store.clear(),
+      get length(): number {
+        return store.size;
+      },
+      key: (i: number): string | null => Array.from(store.keys())[i] ?? null,
+    },
+  });
+});
+describe("VisualTree — Empty-State", () => {
+  test("ohne registrierte Provider rendert sichtbaren Empty-Hint", () => {
+    renderTree(new Map());
+    expect(screen.getByLabelText("Visual Tree (no providers)")).toBeTruthy();
+    expect(screen.getByText(/Keine Tree-Provider aktiv/)).toBeTruthy();
+  });
+  test("Provider-Map vorhanden + emittet leere TreeNode[]: kein Empty-State, kein NavTree-Fallback", () => {
+    const providers = new Map([["text-content", makeStaticProvider([])]]);
+    renderTree(providers);
+    // Nicht im Empty-State (es gibt einen registrierten Provider, der
+    // hat nur kein Knoten emittet). Stattdessen rendert die ProviderBranch
+    // mit dem featureName als Label im aria-tree.
+    expect(screen.queryByLabelText("Visual Tree (no providers)")).toBeNull();
+    expect(screen.getByLabelText("Visual Tree")).toBeTruthy();
+  });
+});
+describe("VisualTree — Provider-Iteration", () => {
+  test("Single-Provider mit static-children rendert Top-Level-Knoten", () => {
+    const providers = new Map([
+      ["text-content", makeStaticProvider([{ label: "Marketing" }, { label: "Legal" }])],
+    ]);
+    renderTree(providers);
+    expect(screen.getByText("Marketing")).toBeTruthy();
+    expect(screen.getByText("Legal")).toBeTruthy();
+  });
+  test("Multi-Provider alphabetisch sortiert nach featureName", () => {
+    // legal-pages kommt alphabetisch vor text-content
+    const providers = new Map<string, TreeChildrenSubscribe>([
+      ["text-content", makeStaticProvider([{ label: "Marketing" }])],
+      ["legal-pages", makeStaticProvider([{ label: "Imprint" }])],
+    ]);
+    renderTree(providers);
+    const branches = document.querySelectorAll("[data-kumiko-tree-branch]");
+    expect(branches[0]?.getAttribute("data-kumiko-tree-branch")).toBe("legal-pages");
+    expect(branches[1]?.getAttribute("data-kumiko-tree-branch")).toBe("text-content");
+  });
+  test("Provider der nicht emittet bleibt im loading-State sichtbar", () => {
+    // Provider ruft emit nie auf (z.B. async-fetch noch im Flug)
+    const noopProvider: TreeChildrenSubscribe = () => () => () => {};
+    const providers = new Map([["slow-feature", noopProvider]]);
+    renderTree(providers);
+    expect(screen.getByText("slow-feature: lädt …")).toBeTruthy();
+  });
+  test("Subscribe-Update: zweiter Emit re-rendert die Liste", () => {
+    const { provider, emit } = makeMutableProvider([{ label: "Hero" }]);
+    const providers = new Map([["text-content", provider]]);
+    renderTree(providers);
+    expect(screen.getByText("Hero")).toBeTruthy();
+    // Provider emittet aktualisierte Liste — Tree muss re-rendern.
+    // act() wrapped den state-Update damit React synchronisiert flushed.
+    act(() => {
+      emit([{ label: "Hero" }, { label: "Pricing" }]);
+    });
+    expect(screen.getByText("Pricing")).toBeTruthy();
+    expect(screen.getByText("Hero")).toBeTruthy();
+  });
+  test("Provider-Unsubscribe wird beim Unmount gecallt", () => {
+    let unsubscribed = false;
+    const provider: TreeChildrenSubscribe = () => (emit) => {
+      emit([{ label: "Foo" }]);
+      return () => {
+        unsubscribed = true;
+      };
+    };
+    const providers = new Map([["test", provider]]);
+    const result = renderTree(providers);
+    expect(unsubscribed).toBe(false);
+    result.unmount();
+    expect(unsubscribed).toBe(true);
+  });
+});
+describe("VisualTree — Click-Dispatch", () => {
+  let cleanup: (() => void) | undefined;
+  afterEach(() => {
+    cleanup?.();
+    cleanup = undefined;
+  });
+  test("Click auf Knoten mit target ruft dispatchTarget mit dem TargetRef", () => {
+    const dispatched: unknown[] = [];
+    cleanup = setDispatchListener((target) => {
+      dispatched.push(target);
+    });
+    const providers = new Map([
+      [
+        "text-content",
+        makeStaticProvider([
+          {
+            label: "Hero",
+            target: { featureId: "text-content", action: "edit", args: { slug: "hero" } },
+          },
+        ]),
+      ],
+    ]);
+    renderTree(providers);
+    fireEvent.click(screen.getByText("Hero"));
+    expect(dispatched).toEqual([
+      { featureId: "text-content", action: "edit", args: { slug: "hero" } },
+    ]);
+  });
+  test('Skeleton-Affordance: state="empty" + createAction rendert + Button und dispatcht createAction.target', () => {
+    // D3-Validation aus visual-tree.md V.1.1-Decisions: Provider-explizit
+    // createAction-Field auf TreeNode mit state="empty" → Tree-Component
+    // zeigt automatisch ein "+"-Icon und dispatcht createAction.target
+    // beim Klick (NICHT node.target — das wäre die Row-onClick-Action).
+    const dispatched: unknown[] = [];
+    cleanup = setDispatchListener((target) => {
+      dispatched.push(target);
+    });
+    const providers = new Map([
+      [
+        "sections",
+        makeStaticProvider([
+          {
+            label: "Sections",
+            state: "empty",
+            createAction: {
+              icon: "plus",
+              label: "Add section",
+              target: { featureId: "sections", action: "create" },
+            },
+          },
+        ]),
+      ],
+    ]);
+    renderTree(providers);
+    // + Button greifbar via aria-label aus createAction.label
+    const addButton = screen.getByLabelText("Add section");
+    fireEvent.click(addButton);
+    expect(dispatched).toEqual([{ featureId: "sections", action: "create" }]);
+  });
+  test("Click auf Container-Knoten (mit children) toggled expand statt Dispatch", () => {
+    const dispatched: unknown[] = [];
+    cleanup = setDispatchListener((target) => {
+      dispatched.push(target);
+    });
+    const providers = new Map([
+      [
+        "text-content",
+        makeStaticProvider([
+          {
+            label: "Marketing",
+            children: [{ label: "Hero" }],
+          },
+        ]),
+      ],
+    ]);
+    renderTree(providers);
+    // Initial collapsed: Hero nicht sichtbar
+    expect(screen.queryByText("Hero")).toBeNull();
+    fireEvent.click(screen.getByText("Marketing"));
+    // Nach Click expanded: Hero sichtbar, kein Dispatch passiert
+    expect(screen.getByText("Hero")).toBeTruthy();
+    expect(dispatched).toEqual([]);
+  });
+});
+describe("VisualTree — localStorage-Persistenz", () => {
+  test("Toggle persistiert expanded-Set ins localStorage pro Workspace", () => {
+    const providers = new Map([
+      ["text-content", makeStaticProvider([{ label: "Marketing", children: [{ label: "Hero" }] }])],
+    ]);
+    renderTree(providers);
+    fireEvent.click(screen.getByText("Marketing"));
+    const stored = window.localStorage.getItem("kumiko:visual-tree:expanded:test-ws");
+    expect(stored).not.toBeNull();
+    const parsed = JSON.parse(stored ?? "[]") as string[];
+    expect(parsed.length).toBe(1);
+    expect(parsed[0]).toContain("Marketing");
+  });
+  test("Re-mount restored expanded-Set aus localStorage", () => {
+    // Setup: persistierter expanded-Set für test-ws-Workspace
+    window.localStorage.setItem(
+      "kumiko:visual-tree:expanded:test-ws",
+      JSON.stringify(["text-content/0-Marketing"]),
+    );
+    const providers = new Map([
+      ["text-content", makeStaticProvider([{ label: "Marketing", children: [{ label: "Hero" }] }])],
+    ]);
+    renderTree(providers);
+    // Marketing ist expandiert → Hero sichtbar ohne Click
+    expect(screen.getByText("Hero")).toBeTruthy();
+  });
+});

package/src/layout/avatar.tsx CHANGED Viewed

@@ -43,7 +43,7 @@ const SIZE_CLASSES: Record<AvatarSize, string> = {
   sm: "size-5 text-[10px]",
   md: "size-6 text-[11px]",
   lg: "size-8 text-xs",
-};
+} satisfies Record<AvatarSize, string>;
 function hashCode(str: string): number {
   // djb2-Variante — schnell, deterministic, gut genug verteilt für

package/src/layout/editor-panel.tsx ADDED Viewed

@@ -0,0 +1,91 @@
+// EditorPanel — V.1.2: Right-side editor panel für Target-Dispatch.
+// Wird sichtbar wenn ein TreeNode mit target angeklickt wird. Zeigt
+// das passende Editor-Component aus dem Resolver-Registry, oder eine
+// Fallback-Info wenn kein Resolver registriert ist.
+// Siehe visual-tree.md V.1.2 + V.1.1-B.
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+import { X } from "lucide-react";
+import type { ComponentType, ReactNode } from "react";
+import { useCallback, useEffect, useState } from "react";
+import { subscribeTargetDispatches } from "./target-resolver-stub";
+export type ResolverComponent = ComponentType<{
+  readonly target: TargetRef;
+  readonly onClose: () => void;
+}>;
+export type EditorPanelProps = {
+  readonly resolvers: ReadonlyMap<string, ResolverComponent>;
+};
+function EditorPanelInner({
+  target,
+  resolvers,
+  onClose,
+}: {
+  readonly target: TargetRef;
+  readonly resolvers: ReadonlyMap<string, ResolverComponent>;
+  readonly onClose: () => void;
+}): ReactNode {
+  const resolverKey = `${target.featureId}:${target.action}`;
+  const Resolver = resolvers.get(resolverKey);
+  if (Resolver !== undefined) {
+    return <Resolver target={target} onClose={onClose} />;
+  }
+  return (
+    <div className="flex flex-col gap-4 p-4">
+      <div className="flex items-center justify-between">
+        <h2 className="text-lg font-semibold">Editor</h2>
+        <button
+          type="button"
+          aria-label="close editor"
+          className="p-1 hover:bg-accent rounded"
+          onClick={onClose}
+        >
+          <X className="size-4" />
+        </button>
+      </div>
+      <div className="text-sm text-muted-foreground space-y-2">
+        <p>
+          Kein Editor f&uuml;r{" "}
+          <code>
+            {target.featureId}:{target.action}
+          </code>{" "}
+          registriert.
+        </p>
+        <pre className="bg-muted p-2 rounded text-xs overflow-auto">
+          {JSON.stringify(target.args, null, 2)}
+        </pre>
+      </div>
+    </div>
+  );
+}
+export function EditorPanel({ resolvers }: EditorPanelProps): ReactNode {
+  const [target, setTarget] = useState<TargetRef | undefined>();
+  useEffect(() => {
+    const unsubscribe = subscribeTargetDispatches((t: TargetRef) => {
+      setTarget(t);
+    });
+    return unsubscribe;
+  }, []);
+  const handleClose = useCallback(() => {
+    setTarget(undefined);
+  }, []);
+  if (target === undefined) return null;
+  return (
+    <div
+      data-kumiko-layout="editor-panel"
+      className="fixed inset-y-0 right-0 z-50 w-[480px] max-w-[90vw] border-l bg-background shadow-xl overflow-y-auto"
+    >
+      <EditorPanelInner target={target} resolvers={resolvers} onClose={handleClose} />
+    </div>
+  );
+}

package/src/layout/target-resolver-stub.tsx ADDED Viewed

@@ -0,0 +1,53 @@
+// TargetResolver — V.1.2: Multi-Listener-TargetDispatch mit Test-Hook.
+// Der V.1.1-Stub (console.debug) wird durch Production-Subscriber
+// ersetzt — EditorPanel, URL-State-Bridge, etc. registrieren sich
+// via subscribeTargetDispatches().
+//
+// Dispatch-Priority:
+//   1. Test-Listener (setDispatchListener) — exklusiv, kein Production-
+//      Subscriber läuft während Tests (Test-Isolation).
+//   2. Production-Subscriber (subscribeTargetDispatches) — alle
+//      registrierten Production-Subscriber.
+//   3. Kein Test-Listener + keine Subscriber → console.debug fallback
+//      (damit unhandled Klicks sichtbar bleiben).
+//
+// Siehe visual-tree.md V.1.2.
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+type DispatchListener = (target: TargetRef) => void;
+let testListener: DispatchListener | undefined;
+const subscribers = new Set<DispatchListener>();
+export function dispatchTarget(target: TargetRef): void {
+  if (testListener !== undefined) {
+    testListener(target);
+    return;
+  }
+  if (subscribers.size > 0) {
+    for (const fn of subscribers) {
+      fn(target);
+    }
+    return;
+  }
+  // biome-ignore lint/suspicious/noConsole: fallback wenn kein Subscriber registered
+  console.debug("[VisualTree] target dispatched (unhandled)", target);
+}
+/** Test-Hook: Exklusiver Spy. Returnt cleanup. */
+export function setDispatchListener(fn: DispatchListener): () => void {
+  testListener = fn;
+  return () => {
+    testListener = undefined;
+  };
+}
+/** Production-Subscriber registrieren. Returnt unsubscribe. Läuft nur
+ *  wenn kein Test-Listener aktiv (Test-Isolation). */
+export function subscribeTargetDispatches(fn: DispatchListener): () => void {
+  subscribers.add(fn);
+  return () => {
+    subscribers.delete(fn);
+  };
+}