@cosmicdrift/kumiko-bundled-features 0.2.3 → 0.4.0

package/src/text-content/web/__tests__/group-blocks.test.ts

@@ -0,0 +1,221 @@
+// @vitest-environment jsdom
+
+import type { TreeNode } from "@cosmicdrift/kumiko-framework/engine";
+import { describe, expect, test } from "vitest";
+import { type BlockSummary, groupBlocksByFolder } from "../client-plugin";
+
+// TreeNode.children ist `readonly TreeNode[] | TreeChildrenSubscribe` —
+// im Provider-Output ist die Subscribe-Form nur für deferred-children
+// gedacht, groupBlocksByFolder produziert ausschließlich statische
+// Array-Children. TypeGuard statt as-Cast (Memory `[Type Assertions]`).
+function childrenArray(children: TreeNode["children"] | undefined): readonly TreeNode[] {
+  if (!Array.isArray(children)) throw new Error("expected static children-array");
+  return children;
+}
+
+// V.1.5d-Helper: groupBlocksByFolder gibt jetzt einen "Content"-Wrapper-
+// Folder zurück. Tests wollen den Inhalt UNTER dem Wrapper prüfen.
+function inside(result: readonly TreeNode[]): readonly TreeNode[] {
+  expect(result).toHaveLength(1);
+  const wrapper = result[0];
+  expect(wrapper?.label).toBe("Content");
+  expect(wrapper?.icon).toBe("folder");
+  return childrenArray(wrapper?.children);
+}
+
+// Helper: BlockSummary mit defaults für die nicht-test-relevanten Felder.
+function block(opts: {
+  slug: string;
+  folder?: string | null;
+  body?: string | null;
+  title?: string;
+}): BlockSummary {
+  return {
+    slug: opts.slug,
+    lang: "de",
+    title: opts.title ?? opts.slug,
+    // Nicht ?? — null soll durchgereicht werden (state="stub"-Test).
+    body: opts.body === undefined ? "irgendwas" : opts.body,
+    folder: opts.folder === undefined ? null : opts.folder,
+    updatedAt: "2026-05-19T00:00:00Z",
+  };
+}
+
+describe("groupBlocksByFolder", () => {
+  test("leeres Array → leeres Array", () => {
+    expect(groupBlocksByFolder([])).toEqual([]);
+  });
+
+  test("folder=null → Root-Node ohne Folder (innerhalb Content-Wrapper)", () => {
+    const nodes = inside(groupBlocksByFolder([block({ slug: "imprint", folder: null })]));
+    expect(nodes).toHaveLength(1);
+    const root = nodes[0];
+    expect(root).toBeDefined();
+    if (!root) return;
+    expect(root.label).toBe("imprint");
+    expect(root.target).toEqual({
+      featureId: "text-content",
+      action: "edit",
+      args: { slug: "imprint", lang: "de" },
+    });
+    expect(root.children).toBeUndefined();
+    expect(root.icon).toBeUndefined();
+  });
+
+  test('folder="page" → Folder-Container mit child', () => {
+    const nodes = inside(
+      groupBlocksByFolder([block({ slug: "hero", folder: "page", title: "Hero" })]),
+    );
+    expect(nodes).toHaveLength(1);
+    const folder = nodes[0];
+    expect(folder).toBeDefined();
+    if (!folder) return;
+    expect(folder.label).toBe("page");
+    expect(folder.icon).toBe("folder");
+    const children = childrenArray(folder.children);
+    expect(children).toHaveLength(1);
+    const child = children[0];
+    expect(child).toBeDefined();
+    if (!child) return;
+    expect(child.label).toBe("Hero");
+    expect(child.target?.args).toEqual({ slug: "hero", lang: "de" });
+  });
+
+  test("mehrere Slugs gleicher Folder → ein Folder mit mehreren children", () => {
+    const nodes = inside(
+      groupBlocksByFolder([
+        block({ slug: "hero", folder: "page", title: "Hero" }),
+        block({ slug: "cta", folder: "page", title: "CTA" }),
+        block({ slug: "footer", folder: "page", title: "Footer" }),
+      ]),
+    );
+    expect(nodes).toHaveLength(1);
+    const folder = nodes[0];
+    expect(folder).toBeDefined();
+    if (!folder) return;
+    expect(folder.label).toBe("page");
+    const children = childrenArray(folder.children);
+    expect(children).toHaveLength(3);
+    const labels = children.map((c) => c.label);
+    expect(labels).toEqual(["Hero", "CTA", "Footer"]);
+  });
+
+  test("mixed root + folder → root-nodes zuerst, dann Folders", () => {
+    const nodes = inside(
+      groupBlocksByFolder([
+        block({ slug: "imprint", folder: null }),
+        block({ slug: "hero", folder: "page" }),
+        block({ slug: "cta", folder: "page" }),
+      ]),
+    );
+    expect(nodes).toHaveLength(2);
+    expect(nodes[0]?.label).toBe("imprint");
+    expect(nodes[0]?.icon).toBeUndefined();
+    expect(nodes[1]?.label).toBe("page");
+    expect(nodes[1]?.icon).toBe("folder");
+  });
+
+  test("Folders alphabetisch sortiert (deterministisch gegen Map-order)", () => {
+    const nodes = inside(
+      groupBlocksByFolder([
+        block({ slug: "x", folder: "zebra" }),
+        block({ slug: "y", folder: "apple" }),
+        block({ slug: "z", folder: "mango" }),
+      ]),
+    );
+    const folderLabels = nodes.map((n) => n.label);
+    expect(folderLabels).toEqual(["apple", "mango", "zebra"]);
+  });
+
+  test('body=null → state="stub" (Designer-Hinweis dass Slug existiert aber leer)', () => {
+    const nodes = inside(groupBlocksByFolder([block({ slug: "draft", body: null })]));
+    expect(nodes[0]?.state).toBe("stub");
+  });
+
+  test('body=string → state="filled"', () => {
+    const nodes = inside(groupBlocksByFolder([block({ slug: "imprint", body: "content" })]));
+    expect(nodes[0]?.state).toBe("filled");
+  });
+
+  test("title leer → fallback auf slug als label", () => {
+    const nodes = inside(groupBlocksByFolder([block({ slug: "untitled-block", title: "" })]));
+    expect(nodes[0]?.label).toBe("untitled-block");
+  });
+
+  test('V.1.6a multi-level folder ("page/marketing") wird genested gerendert', () => {
+    const nodes = inside(
+      groupBlocksByFolder([block({ slug: "hero", folder: "page/marketing", title: "Hero" })]),
+    );
+    expect(nodes).toHaveLength(1);
+    const pageFolder = nodes[0];
+    expect(pageFolder?.label).toBe("page");
+    expect(pageFolder?.icon).toBe("folder");
+    const pageChildren = childrenArray(pageFolder?.children);
+    expect(pageChildren).toHaveLength(1);
+    const marketingFolder = pageChildren[0];
+    expect(marketingFolder?.label).toBe("marketing");
+    expect(marketingFolder?.icon).toBe("folder");
+    const marketingChildren = childrenArray(marketingFolder?.children);
+    expect(marketingChildren).toHaveLength(1);
+    expect(marketingChildren[0]?.label).toBe("Hero");
+    expect(marketingChildren[0]?.target?.args).toEqual({ slug: "hero", lang: "de" });
+  });
+
+  test("V.1.6a shared folder-prefix → ein gemeinsamer parent", () => {
+    // Zwei blocks mit verschachteltem Pfad teilen die ersten Segmente.
+    // page/hero + page/cta + page/marketing/banner → 1× page-folder mit
+    // 3 children (2 leaves + 1 sub-folder).
+    const nodes = inside(
+      groupBlocksByFolder([
+        block({ slug: "hero", folder: "page", title: "Hero" }),
+        block({ slug: "cta", folder: "page", title: "CTA" }),
+        block({ slug: "banner", folder: "page/marketing", title: "Banner" }),
+      ]),
+    );
+    expect(nodes).toHaveLength(1);
+    const pageFolder = nodes[0];
+    expect(pageFolder?.label).toBe("page");
+    const pageChildren = childrenArray(pageFolder?.children);
+    // Leaves first (Hero, CTA), dann sub-folder (marketing alphabetisch).
+    expect(pageChildren.map((c) => c.label)).toEqual(["Hero", "CTA", "marketing"]);
+    expect(pageChildren[2]?.icon).toBe("folder");
+    const marketingChildren = childrenArray(pageChildren[2]?.children);
+    expect(marketingChildren).toHaveLength(1);
+    expect(marketingChildren[0]?.label).toBe("Banner");
+  });
+
+  test("V.1.6a folder/leaf-collision: gleicher Name auf gleicher Ebene", () => {
+    // Edge-Case (advisor-flagged): block mit folder=null, slug="page"
+    // + block mit folder="page" → "page" existiert als Leaf-Root UND
+    // als Folder. Beide bleiben sichtbar; Folder hat Chevron + Folder-
+    // Icon, Leaf hat target + ist klickbar. Renderer-Pattern macht
+    // visuell klar dass es zwei verschiedene Dinge sind.
+    const nodes = inside(
+      groupBlocksByFolder([
+        block({ slug: "page", folder: null, title: "Page-Root" }),
+        block({ slug: "hero", folder: "page", title: "Hero" }),
+      ]),
+    );
+    expect(nodes).toHaveLength(2);
+    const leaf = nodes[0];
+    const folder = nodes[1];
+    expect(leaf?.label).toBe("Page-Root");
+    expect(leaf?.icon).toBeUndefined();
+    expect(leaf?.target).toBeDefined();
+    expect(folder?.label).toBe("page");
+    expect(folder?.icon).toBe("folder");
+    expect(folder?.target).toBeUndefined();
+  });
+
+  test("Wrapper-Folder 'Content' umschließt alle blocks", () => {
+    // V.1.5d Wrapper-Convention: groupBlocksByFolder gibt EINEN Knoten
+    // zurück (den Wrapper), Inhalt liegt eine Ebene tiefer.
+    const result = groupBlocksByFolder([block({ slug: "imprint" })]);
+    expect(result).toHaveLength(1);
+    const wrapper = result[0];
+    expect(wrapper?.label).toBe("Content");
+    expect(wrapper?.icon).toBe("folder");
+    expect(wrapper?.target).toBeUndefined();
+    expect(childrenArray(wrapper?.children)).toHaveLength(1);
+  });
+});

package/src/text-content/web/client-plugin.tsx

@@ -0,0 +1,378 @@
+// @runtime client
+// Client-Feature-Factory für text-content Visual-Tree. Wird vom App-Code
+// in createKumikoApp({ clientFeatures: [textContentClient()] }) eingehängt
+// und liefert den treeProvider der Text-Blocks aus der by-tenant Query
+// lädt, nach `folder`-Field gruppiert und als TreeNode[] emitted.
+//
+// **Folder-Gruppierung V.1.4**: Block.folder !== null → Knoten landet
+// unter einem Container-Knoten mit Label folder. folder === null →
+// Top-Level (root-node). Slug bleibt kebab-only validiert. Beispiele:
+//   - folder="page", slug="hero"  → Folder "page", child "hero"
+//   - folder=null,   slug="imprint" → root-node "imprint"
+//
+// **State**: TreeNode.state = "filled" wenn body gesetzt ist, sonst
+// "stub" (hellgrau, Designer-Hinweis dass Slug existiert aber leer ist).
+//
+// **Fetch statt Subscribe**: V.1.4 ist Fetch-once beim Mount. Unsubscribe
+// ist no-op. V.1.5+ kann SSE-driven Re-Emit einbauen wenn text-block-
+// updated-Events propagiert werden (Stale-Tree-Fix nach save).
+
+import { useShellUser } from "@cosmicdrift/kumiko-bundled-features/auth-email-password/web";
+import { CSRF_HEADER_NAME, readCsrfToken } from "@cosmicdrift/kumiko-dispatcher-live";
+import type {
+  TargetRef,
+  TreeChildrenSubscribe,
+  TreeNode,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { useDispatcher, usePrimitives, useQuery } from "@cosmicdrift/kumiko-renderer";
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer-web";
+import { type FormEvent, type ReactNode, useEffect, useState } from "react";
+import { TextContentHandlers, TextContentQueries } from "../constants";
+
+// Exported für Unit-Test (groupBlocksByFolder ist pure-function ohne
+// fetch/DOM). Public-API für externe Konsumenten ist nicht intendiert —
+// sub-path-Export endet bei textContentClient().
+export type BlockSummary = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly folder: string | null;
+  readonly updatedAt: string;
+};
+
+type ByTenantResponse = {
+  readonly data: { readonly blocks: readonly BlockSummary[] };
+};
+
+// V.1.6a Multi-level Folder-Splitting: `folder` ist ein `/`-separierter
+// Pfad (z.B. "page/marketing"). Der Tree splittet pro Segment und
+// erzeugt nested Folder-Knoten:
+//   block.folder = null              → root-leaf
+//   block.folder = "page"            → 📁 page > leaf
+//   block.folder = "page/marketing"  → 📁 page > 📁 marketing > leaf
+//
+// Walk-or-create-pattern: pro Block durch die Folder-Hierarchie laufen,
+// Folder-Knoten anlegen wo nötig, Leaf am Ende anhängen. Folders pro
+// Ebene alphabetisch sortiert (deterministisch).
+//
+// **Folder/Leaf-Collision** (advisor-Edge-Case): wenn ein Block
+// `folder=null, slug="page"` UND ein anderer `folder="page", slug=...`
+// existieren, leben beide an derselben Ebene — der Folder mit children
+// + ein klickbarer Leaf "page" als root. Visual unterscheidbar (Folder
+// hat Chevron + Folder-Icon, Leaf nicht). Kein Crash, keine Surprise.
+//
+// **V.1.5d Wrapper-Folder "Content"**: alle text-content-Blocks landen
+// unter einem expliziten Top-Level-Folder. Empty-Tree → kein Wrapper.
+
+type FolderNode = {
+  readonly leaves: TreeNode[];
+  readonly subFolders: Map<string, FolderNode>;
+};
+
+function newFolderNode(): FolderNode {
+  return { leaves: [], subFolders: new Map() };
+}
+
+function attachBlock(root: FolderNode, block: BlockSummary): void {
+  const leaf: TreeNode = {
+    label: block.title || block.slug,
+    target: {
+      featureId: "text-content",
+      action: "edit",
+      args: { slug: block.slug, lang: block.lang },
+    },
+    state: block.body ? "filled" : "stub",
+  };
+  if (block.folder === null) {
+    root.leaves.push(leaf);
+    return;
+  }
+  let cur = root;
+  for (const segment of block.folder.split("/")) {
+    let next = cur.subFolders.get(segment);
+    if (next === undefined) {
+      next = newFolderNode();
+      cur.subFolders.set(segment, next);
+    }
+    cur = next;
+  }
+  cur.leaves.push(leaf);
+}
+
+function renderFolderNode(node: FolderNode): TreeNode[] {
+  // Leaves first (root-items), dann Folders alphabetisch.
+  const result: TreeNode[] = [...node.leaves];
+  for (const folderName of [...node.subFolders.keys()].sort()) {
+    const subNode = node.subFolders.get(folderName);
+    if (subNode === undefined) continue;
+    result.push({
+      label: folderName,
+      icon: "folder",
+      state: "filled",
+      children: renderFolderNode(subNode),
+    });
+  }
+  return result;
+}
+
+export function groupBlocksByFolder(blocks: readonly BlockSummary[]): readonly TreeNode[] {
+  const root = newFolderNode();
+  for (const block of blocks) {
+    attachBlock(root, block);
+  }
+  const rendered = renderFolderNode(root);
+  if (rendered.length === 0) return [];
+  return [
+    {
+      label: "Content",
+      icon: "folder",
+      state: "filled",
+      children: rendered,
+    },
+  ];
+}
+
+const treeProvider: TreeChildrenSubscribe = () => (emit, emitError) => {
+  // CSRF-Header bei authenticated requests pflicht (auth-middleware
+  // double-submit pattern). Anonymous/Pre-Login wäre csrf-token=undefined
+  // → header weggelassen → server lässt die anonymous-Variante durch.
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  const csrf = readCsrfToken();
+  if (csrf !== undefined) headers[CSRF_HEADER_NAME] = csrf;
+  fetch("/api/query", {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      type: TextContentQueries.byTenant,
+      payload: {},
+    }),
+  })
+    .then(async (r) => {
+      if (!r.ok) {
+        // 403 (CSRF/auth) oder 5xx — explicit error statt silent empty.
+        const text = await r.text().catch(() => r.statusText);
+        throw new Error(`text-content load failed: ${r.status} ${text}`);
+      }
+      return r.json();
+    })
+    .then((data: ByTenantResponse) => {
+      const nodes = groupBlocksByFolder(data.data.blocks);
+      emit(nodes);
+    })
+    .catch((e) => {
+      // V.1.4: explicit error-Signal via emitError. ProviderBranch zeigt
+      // Banner + Retry-Button. Fallback auf emit([]) wenn der Consumer
+      // kein emitError unterstützt (Tests etc.).
+      if (emitError) {
+        emitError(e instanceof Error ? e : new Error(String(e)));
+      } else {
+        emit([]);
+      }
+    });
+  return () => {};
+};
+
+// V.1.3 echte Edit-Form: lädt aktuelle Werte via by-slug-query, lässt
+// TenantAdmin/SystemAdmin title + body editieren, dispatcht set-write
+// bei Submit. Non-Admin-User sehen die Form read-only mit Hint-Banner —
+// das ist der Kumiko-Weg (Memory `[Sicherheit > Convenience]`: write-
+// permission bleibt opinionated TenantAdmin-only, App-Roles erweitern
+// per Dual-Role-Mapping wenn gewollt).
+//
+// **Stale-Tree-Caveat (V.1.4-Followup)**: TreeProvider ist fetch-once.
+// Nach erfolgreichem Save flippt der visual state="stub"→"filled" in
+// der Sidebar NICHT, bis der User den Workspace re-mountet. Editor selbst
+// ist konsistent (lokaler Form-State trägt die neuen Werte). Echte
+// Lösung: SSE-driven Tree-Refresh oder explicit cache-bust nach set-write.
+
+type TextBlock = {
+  readonly slug: string;
+  readonly lang: string;
+  readonly title: string;
+  readonly body: string | null;
+  readonly folder: string | null;
+  readonly updatedAt: string;
+};
+
+type SetResponse = { readonly slug: string; readonly lang: string; readonly isNew: boolean };
+
+function TextContentEditor({
+  target,
+  onClose,
+}: {
+  readonly target: TargetRef;
+  readonly onClose: () => void;
+}): ReactNode {
+  // @cast-boundary visual-tree-args — TargetRef.args ist erased zu
+  // Record<string, unknown>; der Resolver kennt das Action-Shape (siehe
+  // treeActions.edit-Definition unten) und de-erased pro Action analog
+  // zu Event-Payloads. Optional-Chain absorbiert fehlende Felder ohne
+  // throw, damit der Editor auch bei manuellem URL-Tampering nicht
+  // crasht (TargetRef könnte aus old localStorage / URL-State stammen).
+  const args = target.args as { slug?: string; lang?: string } | undefined;
+  const slug = args?.slug ?? "";
+  const lang = args?.lang ?? "";
+
+  const { Form, Field, Input, Button, Banner } = usePrimitives();
+  const dispatcher = useDispatcher();
+  const user = useShellUser();
+  const canWrite =
+    user?.roles.includes("TenantAdmin") === true || user?.roles.includes("SystemAdmin") === true;
+
+  // Load existing block via by-slug-query. Result ist entweder TextBlock
+  // oder null (slug existiert nicht — create-flow). useQuery returnt
+  // `data: T | null`, initial-loading: data=null + loading=true.
+  const {
+    data: loaded,
+    loading,
+    error: loadError,
+  } = useQuery<TextBlock | null>(
+    TextContentQueries.bySlug,
+    { slug, lang },
+    { enabled: slug !== "" && lang !== "" },
+  );
+
+  // Form-State unabhängig vom geladenen Block. Sync nur initial oder
+  // wenn target.slug+lang wechselt (User springt zwischen Knoten).
+  const [title, setTitle] = useState("");
+  const [body, setBody] = useState("");
+  const [folder, setFolder] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const [saveError, setSaveError] = useState<string | null>(null);
+  const [savedMsg, setSavedMsg] = useState<string | null>(null);
+
+  // Sync loaded data → form state. Trigger sobald loaded-shape eindeutig
+  // ist (data ≠ undefined). loaded === null heißt "Block existiert noch
+  // nicht" — leere Form für create-flow.
+  useEffect(() => {
+    if (loading) return;
+    setTitle(loaded?.title ?? "");
+    setBody(loaded?.body ?? "");
+    setFolder(loaded?.folder ?? "");
+    setSaveError(null);
+    setSavedMsg(null);
+  }, [loading, loaded]);
+
+  const handleSave = async (): Promise<void> => {
+    setSubmitting(true);
+    setSaveError(null);
+    setSavedMsg(null);
+    try {
+      const result = await dispatcher.write<SetResponse>(TextContentHandlers.set, {
+        slug,
+        lang,
+        title,
+        body: body.length > 0 ? body : null,
+        folder: folder.length > 0 ? folder : null,
+      });
+      if (result.isSuccess) {
+        setSavedMsg(result.data.isNew ? "Neu angelegt." : "Gespeichert.");
+      } else {
+        setSaveError(result.error.message ?? result.error.code ?? "Speichern fehlgeschlagen.");
+      }
+    } catch (e) {
+      // Network-blip / dispatcher-throw — sonst bleibt submitting=true,
+      // Save-Button locked-forever, User klickt repeat ohne Feedback.
+      // Generic message reicht: konkreter Recovery-Pfad ist Retry.
+      setSaveError(e instanceof Error ? e.message : "Netzwerkfehler beim Speichern.");
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const onSubmit = (e?: FormEvent): void => {
+    e?.preventDefault();
+    void handleSave();
+  };
+
+  const disabled = submitting || loading || !canWrite;
+
+  return (
+    <div className="flex h-full flex-col">
+      <header className="flex items-center justify-between border-b px-6 py-4">
+        <div>
+          <h2 className="text-lg font-semibold">Text-Block bearbeiten</h2>
+          <p className="text-xs text-muted-foreground">
+            {slug || "—"} ({lang || "—"})
+          </p>
+        </div>
+        <Button variant="secondary" onClick={onClose}>
+          schlie&szlig;en
+        </Button>
+      </header>
+      <div className="flex-1 overflow-y-auto px-6 py-6">
+        <Form onSubmit={onSubmit}>
+          {loading && <Banner variant="loading">Lädt aktuellen Stand…</Banner>}
+          {loadError !== null && (
+            <Banner variant="error">Konnte Block nicht laden: {loadError.code}</Banner>
+          )}
+          {!canWrite && !loading && (
+            <Banner variant="info">
+              Read-only — TenantAdmin- oder SystemAdmin-Rolle f&uuml;r &Auml;nderungen erforderlich.
+            </Banner>
+          )}
+          <Field id="text-content-title" label="Titel" required>
+            <Input
+              kind="text"
+              id="text-content-title"
+              name="text-content-title"
+              value={title}
+              onChange={setTitle}
+              disabled={disabled}
+              required
+            />
+          </Field>
+          <Field id="text-content-folder" label="Ordner (optional)">
+            <Input
+              kind="text"
+              id="text-content-folder"
+              name="text-content-folder"
+              value={folder}
+              onChange={setFolder}
+              disabled={disabled}
+              placeholder="z.B. page oder legal"
+            />
+          </Field>
+          <Field id="text-content-body" label="Inhalt">
+            <Input
+              kind="textarea"
+              id="text-content-body"
+              name="text-content-body"
+              value={body}
+              onChange={setBody}
+              disabled={disabled}
+              rows={14}
+            />
+          </Field>
+          {saveError !== null && <Banner variant="error">{saveError}</Banner>}
+          {savedMsg !== null && <Banner variant="info">{savedMsg}</Banner>}
+          {canWrite && (
+            <Button type="submit" loading={submitting} disabled={disabled}>
+              {submitting ? "Speichern…" : "Speichern"}
+            </Button>
+          )}
+        </Form>
+      </div>
+    </div>
+  );
+}
+
+export function textContentClient(): ClientFeatureDefinition {
+  return {
+    name: "text-content",
+    treeProvider,
+    // V.1.5b: SSE-driven Tree-Refresh. Bei jedem text-block-Event
+    // (created/updated/deleted) ruft ProviderBranch den treeProvider
+    // neu auf → Tree-State spiegelt save sofort wider (Stale-Tree-Fix).
+    treeEntities: ["text-block"],
+    treeActions: {
+      edit: { args: { slug: "" as string, lang: "" as string } },
+      list: {},
+      create: { args: { folder: "" as string } },
+    },
+    resolvers: {
+      "text-content:edit": TextContentEditor,
+    },
+  };
+}

package/src/text-content/web/index.ts

@@ -0,0 +1,8 @@
+// @runtime client
+// Public exports für die Browser-Seite des text-content Features.
+// Wird über den Sub-Path-Export `@cosmicdrift/kumiko-bundled-features/text-content/web`
+// konsumiert — die Server-Seite (defineFeature) lebt in
+// `@cosmicdrift/kumiko-bundled-features/text-content` und hat keine
+// React-/DOM-Deps. Trennung bleibt sauber so wie renderer vs renderer-web.
+
+export { textContentClient } from "./client-plugin";

package/src/tier-engine/feature.ts

@@ -197,7 +197,7 @@ export function createTierEngineFeature<
     // Invalidation: tier-assignment events update the cache.
     r.entityHook("postSave", "tier-assignment", async (result) => {
       // result.data has tenantId + tier (after entity-update merge)
-      const data = result.data as { tenantId?: unknown; tier?: unknown };
+      const data = result.data as { tenantId?: unknown; tier?: unknown }; // @cast-boundary engine-payload
       // skip: defensive type-guard auf payload-shape. Bei korrekt gerenderten
       // entity-events sind beide fields immer strings; ein malformed-payload
       // (custom-handler-bug) würde hier silent zum cache-skip führen statt
@@ -210,7 +210,7 @@ export function createTierEngineFeature<
       );
     });
     r.entityHook("postDelete", "tier-assignment", async (payload) => {
-      const data = payload.data as { tenantId?: unknown };
+      const data = payload.data as { tenantId?: unknown }; // @cast-boundary engine-payload
       // skip: gleiche type-guard semantik wie postSave-hook oben.
       if (typeof data.tenantId !== "string") return;
       cache.delete(data.tenantId as TenantId);
@@ -235,16 +235,16 @@ export function createTierEngineFeature<
         "tenant",
         async (result, ctx) => {
           // result-shape: kumiko-framework's SaveContext mit isNew + data
-          const saveResult = result as { isNew?: unknown; data?: unknown };
+          const saveResult = result as { isNew?: unknown; data?: unknown }; // @cast-boundary engine-payload
           // skip: nur bei tenant-create (initial) — tenant-updates feuern
           // auch postSave aber wir wollen kein neues tier-assignment bei
           // re-keying oder name-update.
           if (saveResult.isNew !== true) return;
-          const data = saveResult.data as { id?: unknown };
+          const data = saveResult.data as { id?: unknown }; // @cast-boundary engine-payload
           // skip: defensive type-guard. Tenant-entity hat id zwingend, aber
           // CrudExecutor's payload-shape ist runtime-unknown.
           if (typeof data.id !== "string") return;
-          const newTenantId = data.id as TenantId;
+          const newTenantId = data.id as TenantId; // @cast-boundary engine-payload
           const aggregateId = tierAssignmentAggregateId(newTenantId);
 
           // skip: defensive — inTransaction phase hat ctx.db immer gesetzt,
@@ -268,7 +268,7 @@ export function createTierEngineFeature<
           // `as TenantDb` gegen future refactor.
           // skip: defensive — sollte im inTransaction nie greifen.
           if (!("raw" in ctx.db)) return;
-          const rawDb = ctx.db.raw as DbConnection;
+          const rawDb = ctx.db.raw as DbConnection; // @cast-boundary db-runner
 
           // Idempotency: stream-existence-check vor create. Pattern aus
           // seedTenant.ts. Bei re-replay (rebuild) nicht versionsbumpen.
@@ -276,7 +276,7 @@ export function createTierEngineFeature<
           const [streamRow] = (await rawDb
             .select({ v: maxFn(eventsTable.version) })
             .from(eventsTable)
-            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[];
+            .where(eq(eventsTable.aggregateId, aggregateId))) as StreamRow[]; // @cast-boundary db-row
           // skip: idempotency — aggregate-stream existiert schon (re-replay
           // nach projection-rebuild oder hook-retry). create() würde
           // version_conflict werfen + tenant-create rollback'n. Pattern aus
@@ -336,7 +336,7 @@ export function createTierEngineFeature<
         // Skalierungs-Pfad (lazy-load + LRU) ist Sprint-8b wenn echtes
         // Bedürfnis entsteht.
         type AssignmentRow = { tenantId: string; tier: string };
-        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[];
+        const rows = (await deps.db.select().from(tierAssignmentTable)) as AssignmentRow[]; // @cast-boundary db-row
         for (const row of rows) {
           cache.set(
             row.tenantId as TenantId,

package/src/user/handlers/find-for-auth.query.ts

@@ -30,7 +30,7 @@ export const findForAuthQuery = defineQueryHandler({
     const condition =
       query.payload.email !== undefined
         ? eq(userTable["email"], query.payload.email)
-        : eq(userTable["id"], query.payload.id as string);
+        : eq(userTable["id"], query.payload.id as string); // @cast-boundary engine-payload
 
     const [row] = await ctx.db.select().from(userTable).where(condition).limit(1);
     return (row as DbRow) ?? null;