@cosmicdrift/kumiko-renderer-web 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,112 @@
 # @cosmicdrift/kumiko-renderer-web
 
+## 0.4.0
+
+### Minor Changes
+
+- 825e7d2: Visual-Tree V.1.4 → V.1.6 — Feature-complete Editor + Folder-Hierarchy + Roving-tabindex.
+
+  **V.1.4** — explicit `folder?: string` Schema-Field auf text-block-entity. Slug bleibt
+  kebab-only validiert, Folder explizit gesetzt. Tree gruppiert via `groupBlocksByFolder`
+  (ersetzt `groupBlocksBySlugPrefix`). `Subscribe<T>` Signature um optional `emitError`
+  erweitert für explicit async-error-Pfade. ProviderBranch zeigt Error-Banner mit
+  Retry-Button. Drift-Test pinnt seedTextBlock-vs-set.write Slug-Validation.
+
+  **V.1.4b** — URL-State-Routing für Editor-Target via `nav.searchParams`. F5 + Back-Button
+  stellen den Editor-State wieder her. Format: `?t=text-content:edit&a_slug=...&a_lang=...`.
+  Plus `useDispatchTarget` hook ersetzt globalen `dispatchTarget` als empfohlenen Production-
+  Pfad (legacy bleibt für Test-Hooks).
+
+  **V.1.5** — Arrow-Key-Navigation (`<aside role="tree">`, ARIA-tree-Pattern) + SSE-driven
+  Tree-Refresh. `ClientFeatureDefinition.treeEntities?: string[]` listet Entity-Namen pro
+  Provider; live-events triggern provider-re-mount → Stale-Tree-state="stub"→"filled"
+  flippt nach save automatisch.
+
+  **V.1.5c+d** — Active-Node-Highlight (explicit blue + 2px border-l + scrollIntoView),
+  VS-Code-Polish (compact spacing, focus-visible, folder-icon-color text-amber, indent-
+  guides per ancestor-depth), Folder-Wrapper für legal-pages ("📁 Legal" + slug-first
+  Verschachtelung) und text-content ("📁 Content").
+
+  **V.1.6** — Multi-level Folder-Splitting (`folder="page/marketing"` → nested folders,
+  walk-or-create-pattern, folder/leaf-collision-tolerant). Roving-tabindex (nur focused-
+  treeitem hat tabIndex=0, Tab cyclt aus dem Tree raus).
+
+  35/35 kumiko check PASS, 13/13 group-blocks + 22/22 text-content integration tests grün.
+  Browser + Keyboard lokal validated.
+
+  **Breaking**: `TreeContext` Type entfernt (V.1.2 SR2-Rip — war nie genutzt). Provider sind
+  session-bound: `TreeChildrenSubscribe = () => Subscribe<T>` statt `(ctx) => Subscribe<T>`.
+
+  **V.1.7-Followups**: useEffect-deps in VisualTree-focus-init (Performance), Cancellation-
+  Token in TreeProvider's fetch (emit-after-unmount-warning), inline-rename, drag-drop,
+  file-icons per slug-extension, parent-jump bei ArrowLeft auf collapsed-item.
+
+### Patch Changes
+
+- Updated dependencies [825e7d2]
+  - @cosmicdrift/kumiko-dispatcher-live@0.4.0
+  - @cosmicdrift/kumiko-headless@0.4.0
+  - @cosmicdrift/kumiko-renderer@0.4.0
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer-web",
-  "version": "0.2.3",
+  "version": "0.4.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,53 @@
     "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.3",
-    "@cosmicdrift/kumiko-headless": "0.2.3",
-    "@cosmicdrift/kumiko-renderer": "0.2.3",
-    "@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.4.0",
+    "@cosmicdrift/kumiko-headless": "0.4.0",
+    "@cosmicdrift/kumiko-renderer": "0.4.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"
+  },
+  "peerDependencies": {
+    "@tailwindcss/cli": "^4.3.0",
+    "tailwindcss": "^4.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/cli": {
+      "optional": false
+    },
+    "tailwindcss": {
+      "optional": false
+    }
   },
   "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 ohne Args). 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();
+  });
+});