@cosmicdrift/kumiko-renderer-web 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @cosmicdrift/kumiko-renderer-web
 
+## 0.3.0
+
+### Minor Changes
+
+- 0.3.0 bringt zwei neue Subsysteme (Step-Engine Tier-3 + Visual-Tree) plus
+  eine AST-Codemod-Pipeline als Vorarbeit für den L2-AI-Layer.
+
+  ### Breaking Changes
+
+  - `skipTransitionGuard` → `unsafeSkipTransitionGuard` (Rename in
+    feature-ast + engine). Der `unsafe`-Prefix macht die Tragweite des
+    Casts sichtbar und ist konsistent zur `unsafeProjectionUpsert`- und
+    `r.rawTable`-Konvention. Migration: 1:1-Ersetzung, keine Verhaltens-Änderung.
+
+  ### Features
+
+  - **Step-Engine M.4 — Tier-3 Workflow-Engine.** Neue Step-Vocabulary
+    `wait`, `waitForEvent`, `retry` ermöglicht persistierte Long-Running-Flows
+    über Job-Boundaries hinweg. Q7 Snapshot-at-Start hängt jedem Step-Run
+    einen SHA-256-Fingerprint des Aggregat-Zustands an, sodass Replays
+    deterministisch gegen den ursprünglichen Eingangszustand laufen.
+  - **Visual-Tree V.1.x — Tree-API + Editor-Panel.** Neue `VisualTree`-
+    Component plus TreeProvider-Pattern; erste TreeProviders für
+    `text-content` und `legal-pages` (CMS-light + Impressum/Privacy).
+    Fundament für den späteren No-Code-Designer (~3000 LOC, 98 Tests).
+  - **Codemod-Pipeline.** AST-basierte Patcher-Module für strukturelle
+    Feature-Edits — wird vom kommenden L2-AI-Layer als Tool-Surface
+    verwendet, ist aber eigenständig nutzbar für ts-morph-style Migrationen.
+  - **user-data-rights Sample-Recipe.** DSGVO Art. 15/17/18/20 vollständig
+    als Sample-Recipe (`samples/recipes/`) inklusive README — zeigt die
+    Export- und Forget-Pipeline gegen den `compliance-profiles`-Default
+    (`eu-dsgvo`).
+
+  ### Fixes
+
+  - `tier-engine`: auto-default-tier-Hook benutzt jetzt `ctx.db.raw` für
+    Event-Store-Operationen (#37, vorher: stiller Bug, 22 Tage live).
+  - `engine`: unsafe-projection-upsert nutzt `as never` statt `as any` —
+    schmaler Cast-Surface, weniger Compiler-Knebel.
+  - `visual-tree`: runtime-isolation marker für client-konsumierte Files,
+    damit der Multi-Entry-Build den richtigen Bundle-Split bekommt.
+  - `feature-ast`: vollständiger `unsafeSkipTransitionGuard`-Rename (war
+    in zwei Modulen noch der alte Name).
+  - `framework`: Error-Reasons + `noConsole`-Lint + No-Date-API-Guard
+    wieder push-ready.
+
+  ### Library-Updates
+
+  hono 4.12, jose 6.2, stripe 22.1, meilisearch 0.58, marked 18,
+  bun-types 1.3.13, lucide-react 1.14, bullmq 5.76, ioredis 5.10,
+  i18next 26.0, react + radix-ui-primitives auf aktuelle Minors.
+
+### Patch Changes
+
+- Updated dependencies
+  - @cosmicdrift/kumiko-dispatcher-live@0.3.0
+  - @cosmicdrift/kumiko-headless@0.3.0
+  - @cosmicdrift/kumiko-renderer@0.3.0
+
+## 0.2.3
+
+### Patch Changes
+
+- @cosmicdrift/kumiko-dispatcher-live@0.2.3
+- @cosmicdrift/kumiko-headless@0.2.3
+- @cosmicdrift/kumiko-renderer@0.2.3
+
 ## 0.2.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Web-platform bindings for @cosmicdrift/kumiko-renderer. HTML default-primitives, browser history-based navigation, EventSource-backed live events, and a one-call createKumikoApp that mounts the whole stack via react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -9,38 +9,41 @@
     "runtime": "client"
   },
   "exports": {
-    ".": "./src/index.ts",
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.2.2",
-    "@cosmicdrift/kumiko-headless": "0.2.2",
-    "@cosmicdrift/kumiko-renderer": "0.2.2",
-    "@radix-ui/react-dialog": "^1.1.6",
-    "@radix-ui/react-dropdown-menu": "^2.1.6",
-    "@radix-ui/react-label": "^2.1.2",
-    "@radix-ui/react-popover": "^1.1.6",
-    "@radix-ui/react-select": "^2.1.6",
-    "@radix-ui/react-slot": "^1.1.2",
-    "@radix-ui/react-toast": "^1.2.6",
-    "@radix-ui/react-tooltip": "^1.1.8",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.3.0",
+    "@cosmicdrift/kumiko-headless": "0.3.0",
+    "@cosmicdrift/kumiko-renderer": "0.3.0",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-select": "^2.2.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-toast": "^1.2.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "lucide-react": "^1.11.0",
-    "react": "^19.2.0",
+    "lucide-react": "^1.14.0",
+    "react": "^19.2.6",
     "react-day-picker": "^9.14.0",
-    "react-dom": "^19.2.0",
-    "tailwind-merge": "^3.0.2"
+    "react-dom": "^19.2.6",
+    "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
-    "@tailwindcss/cli": "^4.0.0",
-    "@testing-library/react": "^16.3.0",
+    "@tailwindcss/cli": "^4.3.0",
+    "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "jsdom": "^29.1.0",
-    "tailwindcss": "^4.0.0"
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "jsdom": "^29.1.1",
+    "tailwindcss": "^4.3.0"
   },
   "repository": {
     "type": "git",

package/src/__tests__/visual-tree-integration.test.tsx

@@ -0,0 +1,315 @@
+// @vitest-environment jsdom
+//
+// V.1.1-D Integration-Test — End-to-End-Beweis für die Schleife
+// `clientFeatures.treeProvider → useTreeProviders → VisualTree →
+// TreeNodeRenderer → Click → dispatchTarget`.
+//
+// Im Gegensatz zum visual-tree.test.tsx (isolierte VisualTree-Component
+// mit Mock-Providers) mountet dieser Test den vollen WorkspaceShell mit
+// zwei Workspaces (nav + tree) und zwei Tree-Provider-clientFeatures.
+// Bewert wird:
+//   1. Provider-Iteration: beide Top-Level-Knoten landen im DOM
+//      (alphabetisch nach featureName)
+//   2. Subscribe-Update: zweiter Emit eines Providers re-rendert die
+//      Sidebar ohne Workspace-Switch
+//   3. Stub-Dispatch: Click auf Knoten mit target ruft dispatch mit
+//      richtigem TargetRef
+//   4. Workspace-Switch: nav-Workspace zeigt NavTree, tree-Workspace
+//      zeigt VisualTree mit beiden Provider-Beiträgen
+//
+// **Memory `[Kein Fake-Dispatcher]`-Note**: V.1.1 hat keine HTTP-Calls
+// (Tree-Provider sind reine Client-Functions die nur ctx.tenantId
+// lesen). Echtes setupTestStack kommt mit V.1.2 wenn text-content's
+// Slug-Liste durch die Server-Pipeline geht.
+
+import type { TreeChildrenSubscribe, TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import type { FeatureSchema, WorkspaceSchema } from "@cosmicdrift/kumiko-renderer";
+import {
+  createStaticLocaleResolver,
+  LocaleProvider,
+  NavProvider,
+  PrimitivesProvider,
+} from "@cosmicdrift/kumiko-renderer";
+import { act, fireEvent, render, screen } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { useBrowserNavApi } from "../app/nav";
+import { TreeProvidersProvider } from "../app/tree-providers-context";
+import { setDispatchListener } from "../layout/target-resolver-stub";
+import { WorkspaceShell } from "../layout/workspace-shell";
+import { defaultPrimitives } from "../primitives";
+
+// localStorage-Mock (vitest+Bun-Runtime liefert nur partielles
+// localStorage). Pro Test frische Map damit Tests sauber isoliert sind.
+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,
+    },
+  });
+  window.history.replaceState(null, "", "/");
+});
+
+function ws(
+  id: string,
+  options: {
+    label: string;
+    isDefault?: boolean;
+    navigation?: "nav" | "tree";
+    navMembers?: readonly string[];
+  },
+): WorkspaceSchema {
+  return {
+    definition: {
+      id,
+      label: options.label,
+      access: { openToAll: true },
+      ...(options.isDefault === true && { default: true }),
+      ...(options.navigation !== undefined && { navigation: options.navigation }),
+    },
+    navMembers: options.navMembers ?? [],
+  };
+}
+
+function makeStaticProvider(nodes: readonly TreeNode[]): TreeChildrenSubscribe {
+  return () => (emit) => {
+    emit(nodes);
+    return () => {};
+  };
+}
+
+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 renderShellWithTreeProviders(
+  schema: FeatureSchema,
+  treeProviders: ReadonlyMap<string, TreeChildrenSubscribe>,
+): ReturnType<typeof render> {
+  function Wrapper({ children }: { readonly children: ReactNode }): ReactNode {
+    const nav = useBrowserNavApi({ hasWorkspaces: true });
+    return (
+      <LocaleProvider resolver={createStaticLocaleResolver()}>
+        <PrimitivesProvider value={defaultPrimitives}>
+          <NavProvider value={nav}>
+            <TreeProvidersProvider value={treeProviders}>{children}</TreeProvidersProvider>
+          </NavProvider>
+        </PrimitivesProvider>
+      </LocaleProvider>
+    );
+  }
+  return render(
+    <WorkspaceShell brand={<div>Brand</div>} schema={schema} user={{ id: "u1", roles: [] }}>
+      <div>content</div>
+    </WorkspaceShell>,
+    { wrapper: Wrapper },
+  );
+}
+
+describe("V.1.1-D Integration — Provider-Iteration + Subscribe + Dispatch", () => {
+  let cleanup: (() => void) | undefined;
+  afterEach(() => {
+    cleanup?.();
+    cleanup = undefined;
+  });
+
+  test("Provider-Iteration: beide Features landen im DOM, alphabetisch sortiert", () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [],
+      workspaces: [
+        ws("visual", {
+          label: "Visual",
+          isDefault: true,
+          navigation: "tree",
+        }),
+      ],
+    } as const;
+
+    const treeProviders = new Map<string, TreeChildrenSubscribe>([
+      ["text-content", makeStaticProvider([{ label: "Marketing" }])],
+      ["legal-pages", makeStaticProvider([{ label: "Imprint" }])],
+    ]);
+
+    renderShellWithTreeProviders(schema, treeProviders);
+
+    expect(screen.getByText("Marketing")).toBeTruthy();
+    expect(screen.getByText("Imprint")).toBeTruthy();
+
+    // Reihenfolge: legal-pages (l < t) kommt vor text-content
+    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("Subscribe-Update ohne Workspace-Switch: zweiter Emit re-rendert", () => {
+    const { provider, emit } = makeMutableProvider([{ label: "Hero" }]);
+
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [],
+      workspaces: [ws("visual", { label: "Visual", isDefault: true, navigation: "tree" })],
+    } as const;
+
+    const treeProviders = new Map([["text-content", provider]]);
+
+    renderShellWithTreeProviders(schema, treeProviders);
+    expect(screen.getByText("Hero")).toBeTruthy();
+
+    act(() => {
+      emit([{ label: "Hero" }, { label: "Pricing" }, { label: "Footer" }]);
+    });
+
+    expect(screen.getByText("Pricing")).toBeTruthy();
+    expect(screen.getByText("Footer")).toBeTruthy();
+  });
+
+  test("Stub-Dispatch: Click → setDispatchListener-Spy bekommt richtige TargetRef", () => {
+    const dispatched: unknown[] = [];
+    cleanup = setDispatchListener((target) => {
+      dispatched.push(target);
+    });
+
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [],
+      workspaces: [ws("visual", { label: "Visual", isDefault: true, navigation: "tree" })],
+    } as const;
+
+    const treeProviders = new Map<string, TreeChildrenSubscribe>([
+      [
+        "text-content",
+        makeStaticProvider([
+          {
+            label: "Imprint",
+            target: {
+              featureId: "text-content",
+              action: "edit",
+              args: { slug: "imprint" },
+            },
+          },
+        ]),
+      ],
+    ]);
+
+    renderShellWithTreeProviders(schema, treeProviders);
+    fireEvent.click(screen.getByText("Imprint"));
+
+    expect(dispatched).toEqual([
+      {
+        featureId: "text-content",
+        action: "edit",
+        args: { slug: "imprint" },
+      },
+    ]);
+  });
+
+  test("Workspace-Switch: nav-Workspace zeigt NavTree, tree-Workspace zeigt VisualTree-Provider", () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [{ id: "list", label: "Builder-List" }],
+      workspaces: [
+        ws("admin", {
+          label: "Admin",
+          isDefault: true,
+          navigation: "nav",
+          navMembers: ["demo:nav:list"],
+        }),
+        ws("visual", {
+          label: "Visual",
+          navigation: "tree",
+        }),
+      ],
+    } as const;
+
+    const treeProviders = new Map<string, TreeChildrenSubscribe>([
+      ["text-content", makeStaticProvider([{ label: "Marketing" }])],
+    ]);
+
+    renderShellWithTreeProviders(schema, treeProviders);
+
+    // Initial: admin-Workspace → NavTree mit "Builder-List"
+    expect(screen.getByText("Builder-List")).toBeTruthy();
+    expect(screen.queryByText("Marketing")).toBeNull();
+
+    // Switch zu visual → VisualTree mit Provider-Beitrag
+    fireEvent.click(screen.getByTestId("workspace-tab-visual"));
+    expect(screen.getByText("Marketing")).toBeTruthy();
+    expect(screen.queryByText("Builder-List")).toBeNull();
+
+    // Zurück zu admin → NavTree wieder
+    fireEvent.click(screen.getByTestId("workspace-tab-admin"));
+    expect(screen.getByText("Builder-List")).toBeTruthy();
+    expect(screen.queryByText("Marketing")).toBeNull();
+  });
+
+  test("localStorage-Persistenz: Toggle persistiert pro Workspace, Re-Mount restored", () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [],
+      workspaces: [ws("visual", { label: "Visual", isDefault: true, navigation: "tree" })],
+    } as const;
+
+    const treeProviders = new Map<string, TreeChildrenSubscribe>([
+      ["text-content", makeStaticProvider([{ label: "Marketing", children: [{ label: "Hero" }] }])],
+    ]);
+
+    const result = renderShellWithTreeProviders(schema, treeProviders);
+
+    // Initial collapsed: Hero nicht sichtbar
+    expect(screen.queryByText("Hero")).toBeNull();
+
+    // Toggle: Marketing ausklappen
+    fireEvent.click(screen.getByText("Marketing"));
+    expect(screen.getByText("Hero")).toBeTruthy();
+
+    // localStorage hat den Persisted-State
+    const stored = window.localStorage.getItem("kumiko:visual-tree:expanded:visual");
+    expect(stored).not.toBeNull();
+    expect(JSON.parse(stored ?? "[]")).toContain("text-content/0-Marketing");
+
+    // Re-Mount mit gleichem Workspace → expanded restored
+    result.unmount();
+    renderShellWithTreeProviders(schema, treeProviders);
+    expect(screen.getByText("Hero")).toBeTruthy();
+  });
+});

package/src/__tests__/workspace-shell.test.tsx

@@ -59,6 +59,7 @@ function ws(
     openToAll?: boolean;
     isDefault?: boolean;
     navMembers?: readonly string[];
+    navigation?: "nav" | "tree";
   } = {},
 ): WorkspaceSchema {
   const access = options.openToAll
@@ -73,6 +74,7 @@ function ws(
       ...(options.order !== undefined && { order: options.order }),
       ...(access !== undefined && { access }),
       ...(options.isDefault === true && { default: true }),
+      ...(options.navigation !== undefined && { navigation: options.navigation }),
     },
     navMembers: options.navMembers ?? [],
   };
@@ -770,3 +772,143 @@ describe("WorkspaceShell — AppSchema (multi-feature)", () => {
     expect(screen.getByText("List")).toBeTruthy();
   });
 });
+
+// ---------------------------------------------------------------------------
+// navigation-Mode-Switch — Phase 0 Schicht 3 / V.1.
+// Workspace mit `navigation: "tree"` mountet den Visual-Tree-Stub statt
+// NavTree. Default (kein navigation oder navigation="nav") hält das
+// existing NavTree-Verhalten — kein Breaking-Change für Apps die Visual-
+// Tree nicht aktivieren. Echte Tree-Component kommt in V.1.1.
+// Siehe docs/plans/architecture/visual-tree.md A1.
+// ---------------------------------------------------------------------------
+
+describe("WorkspaceShell — navigation-Mode (Visual-Tree opt-in)", () => {
+  test('navigation: "tree" mountet den Visual-Tree-Stub statt NavTree', () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [{ id: "list", label: "List" }],
+      workspaces: [
+        ws("visual", {
+          label: "Visual",
+          openToAll: true,
+          isDefault: true,
+          navigation: "tree",
+          navMembers: ["demo:nav:list"],
+        }),
+      ],
+    } as const;
+
+    renderShell(
+      <WorkspaceShell brand={<div>Brand</div>} schema={schema} user={{ id: "u1", roles: [] }}>
+        <div>content</div>
+      </WorkspaceShell>,
+    );
+    // Stub-Marker rendert
+    expect(screen.getByLabelText("Visual Tree (no providers)")).toBeTruthy();
+    // NavTree wäre durch das nav-Item "List" sichtbar — darf hier NICHT
+    // rendern (Tree-Mode ersetzt NavTree komplett)
+    expect(screen.queryByText("List")).toBeNull();
+  });
+
+  test('navigation: "nav" mountet NavTree (default-äquivalent)', () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [{ id: "list", label: "List" }],
+      workspaces: [
+        ws("admin", {
+          label: "Admin",
+          openToAll: true,
+          isDefault: true,
+          navigation: "nav",
+          navMembers: ["demo:nav:list"],
+        }),
+      ],
+    } as const;
+
+    renderShell(
+      <WorkspaceShell brand={<div>Brand</div>} schema={schema} user={{ id: "u1", roles: [] }}>
+        <div>content</div>
+      </WorkspaceShell>,
+    );
+    expect(screen.getByText("List")).toBeTruthy();
+    expect(screen.queryByLabelText("Visual Tree (no providers)")).toBeNull();
+  });
+
+  test("workspace ohne navigation-Property defaultet zu NavTree (Backwards-Compat)", () => {
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [{ id: "list", label: "List" }],
+      workspaces: [
+        // Keine `navigation`-Property → existing Apps müssen exakt so
+        // weiter laufen wie vor V.1
+        ws("admin", {
+          label: "Admin",
+          openToAll: true,
+          isDefault: true,
+          navMembers: ["demo:nav:list"],
+        }),
+      ],
+    } as const;
+
+    renderShell(
+      <WorkspaceShell brand={<div>Brand</div>} schema={schema} user={{ id: "u1", roles: [] }}>
+        <div>content</div>
+      </WorkspaceShell>,
+    );
+    expect(screen.getByText("List")).toBeTruthy();
+    expect(screen.queryByLabelText("Visual Tree (no providers)")).toBeNull();
+  });
+
+  test("Switcher-Toggle re-rendert Sidebar zwischen NavTree und Stub", () => {
+    // Multi-Workspace-Setup: beide accessible, einer nav, einer tree.
+    // Single-mount-Tests können nicht beweisen dass der conditional
+    // render bei prop-change sauber re-rendert — das ist die echte UX
+    // (User klickt im Switcher zwischen Modi). Dieser Test pinnt das.
+    const schema = {
+      featureName: "demo",
+      entities: {},
+      screens: [],
+      navs: [{ id: "list", label: "List" }],
+      workspaces: [
+        ws("admin", {
+          label: "Admin",
+          openToAll: true,
+          isDefault: true,
+          navigation: "nav",
+          navMembers: ["demo:nav:list"],
+        }),
+        ws("visual", {
+          label: "Visual",
+          openToAll: true,
+          navigation: "tree",
+        }),
+      ],
+    } as const;
+
+    renderShell(
+      <WorkspaceShell brand={<div>Brand</div>} schema={schema} user={{ id: "u1", roles: [] }}>
+        <div>content</div>
+      </WorkspaceShell>,
+    );
+
+    // Initial: admin-Workspace (default) aktiv → NavTree sichtbar, kein Stub
+    expect(screen.getByText("List")).toBeTruthy();
+    expect(screen.queryByLabelText("Visual Tree (no providers)")).toBeNull();
+
+    // Switch zu visual-Workspace via Switcher-Click
+    fireEvent.click(screen.getByTestId("workspace-tab-visual"));
+    expect(screen.getByLabelText("Visual Tree (no providers)")).toBeTruthy();
+    expect(screen.queryByText("List")).toBeNull();
+
+    // Zurück zu admin → NavTree wieder, Stub weg
+    fireEvent.click(screen.getByTestId("workspace-tab-admin"));
+    expect(screen.getByText("List")).toBeTruthy();
+    expect(screen.queryByLabelText("Visual Tree (no providers)")).toBeNull();
+  });
+});

package/src/app/client-plugin.tsx

@@ -9,6 +9,11 @@
 // ganz außen gestackt, dann alle Gates nach innen. So hat jeder Gate
 // Zugriff auf jeden Provider, egal welches Feature ihn gebracht hat.
 
+import type {
+  TargetRef,
+  TreeActionDef,
+  TreeChildrenSubscribe,
+} from "@cosmicdrift/kumiko-framework/engine";
 import type { ColumnRendererComponent, TranslationsByLocale } from "@cosmicdrift/kumiko-renderer";
 import type { ComponentType, ReactNode } from "react";
 
@@ -45,6 +50,31 @@ export type ClientFeatureDefinition = {
    *  echte JSX-Renderer leben im Client-Bundle. Last-Wins bei Key-
    *  Kollision über mehrere Features. */
   readonly columnRenderers?: Readonly<Record<string, ColumnRendererComponent>>;
+  /** Tree-Provider für `r.workspace({ navigation: "tree" })`-Workspaces
+   *  (Visual-Tree). Wird beim Mount des Tree-Workspaces mit ctx aufgerufen,
+   *  emittiert TreeNode[] die in der Sidebar gerendert werden. Closure-
+   *  Distribution gleicher Mechanismus wie `columnRenderers` — Server-
+   *  Registry kennt nur „dass es das gibt", echte Function lebt
+   *  client-side. Spiegelt das server-side `r.tree(provider)` aus dem
+   *  Feature; bundled-features liefern beide Seiten konsistent.
+   *  Siehe visual-tree.md V.1.1-Distribution. */
+  readonly treeProvider?: TreeChildrenSubscribe;
+  /** Tree-Actions-Schema — die Action-Map die `buildTarget` compile-time
+   *  validiert. Erased-Runtime-Surface; typed Handle wandert separat
+   *  via Server-Feature setup-export (FeatureDefinition.exports.handle).
+   *  Identisch zur server-side `r.treeActions(...)`-Map; bundled-
+   *  features liefern beide Seiten konsistent. */
+  readonly treeActions?: Readonly<Record<string, TreeActionDef>>;
+
+  /** Editor-Resolver-Komponenten pro featureId:action-Key. Wenn ein
+   *  TreeNode mit target angeklickt wird, schlägt der EditorPanel das
+   *  Component hier nach und rendert es. Komponenten erhalten target
+   *  (mit args) und eine onClose-Callback. Ohne registrierten Resolver
+   *  zeigt der EditorPanel einen Info-Fallback.
+   *  Siehe visual-tree.md V.1.2. */
+  readonly resolvers?: Readonly<
+    Record<string, ComponentType<{ readonly target: TargetRef; readonly onClose: () => void }>>
+  >;
 };
 
 /** Wickelt einen ReactNode durch eine Liste von Providern/Gates von