@schlenkr/ragents 0.1.0

package/plugins/ragents.actor-programs/client-ui/FlowDiagram.tsx

@@ -0,0 +1,234 @@
+import React, { lazy, Suspense, useEffect, useMemo, useState } from "react";
+import { cn } from "../../../apps/web/src/ui";
+import type { Edge, Node } from "@xyflow/react";
+import type { ElkNode } from "elkjs/lib/elk-api";
+import type { FlowDiagramProps } from "./flow-diagram-contracts";
+
+type CardItem = NonNullable<FlowDiagramProps["nodes"][number]["items"]>[number] & { labelLines: string; detailLines?: string };
+export interface GraphBounds { x: number; y: number; width: number; height: number }
+type CardData = FlowDiagramProps["nodes"][number] & { labelLines: string; detailLines?: string; itemLines: CardItem[]; direction: "right" | "down"; detailLevel: "full" | "summary"; onAction?: FlowDiagramProps["onAction"] };
+export type CardNode = Node<CardData, "card">;
+type EdgeStatus = NonNullable<FlowDiagramProps["edges"][number]["status"]>;
+export type RouteEdge = Edge<{ path: string; x: number; y: number; rotated?: boolean; labelWidth?: number; status?: EdgeStatus }, "route">;
+export type Link = FlowDiagramProps["edges"][number] & { id: string };
+export interface Placement { nodes: CardNode[]; edges: RouteEdge[]; bounds: GraphBounds }
+interface Layout { key: string; nodes: CardNode[]; edges: RouteEdge[]; bounds?: GraphBounds; error?: string }
+interface Point { x: number; y: number }
+
+function textMeasure(): (text: string) => number {
+  const canvas = typeof document === "undefined" ? undefined : document.createElement("canvas").getContext("2d");
+  if (canvas) canvas.font = `600 16px ${getComputedStyle(document.documentElement).getPropertyValue("--font-sans").trim() || "sans-serif"}`;
+  return text => canvas ? canvas.measureText(text).width : text.length * 10;
+}
+
+function wrap(text: string, width = 204): string {
+  const textWidth = textMeasure();
+  return text.split("\n").flatMap((paragraph) => {
+    const lines: string[] = [];
+    let line = "";
+    for (const word of paragraph.split(/\s+/)) {
+      const next = line ? `${line} ${word}` : word;
+      if (textWidth(next) <= width) { line = next; continue; }
+      if (line) { lines.push(line); line = ""; }
+      for (const character of word) {
+        if (line && textWidth(line + character) > width) { lines.push(line); line = character; }
+        else line += character;
+      }
+    }
+    lines.push(line);
+    return lines;
+  }).join("\n");
+}
+
+function summarize(text: string, width: number, count: number): string {
+  const lines = wrap(text, width).split("\n");
+  if (lines.length <= count) return lines.join("\n");
+  const textWidth = textMeasure();
+  let last = lines[count - 1]!;
+  while (last && textWidth(last + "...") > width) last = last.slice(0, -1);
+  return [...lines.slice(0, count - 1), last.trimEnd() + "..."].join("\n");
+}
+
+const edgeStatuses = ["pending", "active", "done", "blocked"];
+
+function prepare({ nodes, edges, direction = "right", height = 360, viewport = "interactive", detailLevel = "summary", layout = "layered" }: FlowDiagramProps) {
+  if (viewport !== "interactive" && viewport !== "fit-width" && viewport !== "fit") throw new Error("Unbekannter Diagrammansichtsmodus.");
+  if (!Number.isFinite(height) || height <= 0) throw new Error("Die Diagrammhöhe muss positiv sein.");
+  if (direction !== "right" && direction !== "down") throw new Error("Unbekannte Diagrammrichtung.");
+  if (detailLevel !== "full" && detailLevel !== "summary") throw new Error("Unbekannte Diagrammdetailstufe.");
+  if (layout !== "layered" && layout !== "star") throw new Error("Unbekannte Diagrammanordnung.");
+  const summary = detailLevel === "summary";
+  const textWidth = textMeasure();
+  const ids = new Set<string>();
+  const cards = nodes.map((node): CardNode => {
+    if (typeof node.id !== "string" || !node.id.trim() || ids.has(node.id)) throw new Error("Knoten benötigen eindeutige, nicht leere IDs.");
+    ids.add(node.id);
+    if (typeof node.label !== "string" || (node.detail !== undefined && typeof node.detail !== "string")) throw new Error("Knotenbeschriftungen müssen Text sein.");
+    if (node.status !== undefined && !["pending", "active", "done", "blocked"].includes(node.status)) throw new Error("Unbekannter Knotenstatus.");
+    if (node.running !== undefined && typeof node.running !== "boolean") throw new Error("Knotenaktivität muss ein Wahrheitswert sein.");
+    if (node.kind !== undefined && !["actor", "agent", "service"].includes(node.kind)) throw new Error("Unbekannte Knotenart.");
+    const labelLines = summary ? summarize(node.label, 284, 2) : wrap(node.label);
+    const detailLines = summary || node.detail === undefined ? undefined : wrap(node.detail);
+    if (node.items !== undefined && !Array.isArray(node.items)) throw new Error("Knotenpunkte müssen eine Liste sein.");
+    const itemLines = (node.items ?? []).map((item) => {
+      if (typeof item.label !== "string" || (item.detail !== undefined && typeof item.detail !== "string")) throw new Error("Punktbeschriftungen müssen Text sein.");
+      if (item.status !== undefined && !["pending", "active", "done", "blocked", "skipped"].includes(item.status)) throw new Error("Unbekannter Punktstatus.");
+      return { ...item, labelLines: wrap(item.label, summary ? 256 : 176), detailLines: summary || item.detail === undefined ? undefined : wrap(item.detail) };
+    });
+    if (node.actions !== undefined && !Array.isArray(node.actions)) throw new Error("Knotenaktionen müssen eine Liste sein.");
+    const actionIds = new Set<string>();
+    for (const action of node.actions ?? []) {
+      if (typeof action.id !== "string" || !action.id.trim() || actionIds.has(action.id)) throw new Error("Aktionen benötigen eindeutige, nicht leere IDs.");
+      actionIds.add(action.id);
+      if (typeof action.label !== "string") throw new Error("Aktionsbeschriftungen müssen Text sein.");
+    }
+    const itemsHeight = summary ? itemLines.reduce((height, item) => height + 12 + item.labelLines.split("\n").length * 24, 0) : itemLines.reduce((height, item) => height + 24 + item.labelLines.split("\n").length * 24 + 24 + (item.detailLines === undefined ? 0 : item.detailLines.split("\n").length * 24), 0);
+    const actionsHeight = node.actions?.length ? 49 : 0;
+    const height = itemsHeight + actionsHeight + (summary ? 50 : 60) + labelLines.split("\n").length * 24 + (detailLines === undefined ? 0 : 24 + detailLines.split("\n").length * 24);
+    return { id: node.id, type: "card", position: { x: 0, y: 0 }, width: summary ? 320 : 240, height, data: { ...node, labelLines, detailLines, itemLines, direction, detailLevel } };
+  });
+  const edgeIds = new Set<string>();
+  const links = edges.map((edge, index): Link => {
+    const id = edge.id ?? `flow-edge-${index}`;
+    if (typeof id !== "string" || !id.trim() || edgeIds.has(id)) throw new Error("Verbindungen benötigen eindeutige, nicht leere IDs.");
+    edgeIds.add(id);
+    if (!ids.has(edge.source) || !ids.has(edge.target)) throw new Error("Eine Verbindung verweist auf einen fehlenden Knoten.");
+    if (edge.kind !== undefined && edge.kind !== "return") throw new Error("Unbekannte Verbindungsart.");
+    if (edge.status !== undefined && !edgeStatuses.includes(edge.status)) throw new Error("Unbekannter Verbindungsstatus.");
+    if (edge.label !== undefined && typeof edge.label !== "string") throw new Error("Verbindungsbeschriftungen müssen Text sein.");
+    return { ...edge, id };
+  });
+  const key = JSON.stringify([layout, direction, cards.map(({ id, width, height }) => [id, width, height]), links.map(({ id, source, target, label, kind }) => [id, source, target, kind, label === undefined ? 0 : Math.ceil(textWidth(label))])]);
+  return { key, cards, links, direction, layout };
+}
+
+function bounds(points: Point[]): GraphBounds {
+  const x = Math.min(...points.map(point => point.x)) - 16;
+  const y = Math.min(...points.map(point => point.y)) - 16;
+  return { x, y, width: Math.max(...points.map(point => point.x)) + 16 - x, height: Math.max(...points.map(point => point.y)) + 16 - y };
+}
+
+const corners = (nodes: CardNode[]): Point[] => nodes.flatMap(node => [{ x: node.position.x, y: node.position.y }, { x: node.position.x + node.width!, y: node.position.y + node.height! }]);
+
+export function starLayout(cards: CardNode[], links: Link[]): Placement {
+  const [hub, ...rest] = cards;
+  const gap = 24;
+  const rightCount = Math.ceil(rest.length / 2);
+  const columns = [{ side: 1, cards: rest.slice(0, rightCount) }, { side: -1, cards: rest.slice(rightCount) }];
+  const rows = new Map<string, { side: number; relativeY: number }>();
+  const placed = columns.flatMap(({ side, cards: column }) => {
+    const total = column.reduce((sum, card) => sum + card.height!, 0) + gap * (column.length - 1);
+    let top = -total / 2;
+    return column.map((card, index) => {
+      const relativeY = column.length < 2 ? 0 : index * 2 / (column.length - 1) - 1;
+      const distance = hub!.width! / 2 + 120 + card.width! / 2;
+      const y = top + card.height! / 2;
+      top += card.height! + gap;
+      rows.set(card.id, { side, relativeY });
+      return { ...card, position: { x: side * distance - card.width! / 2, y: y - card.height! / 2 } };
+    });
+  });
+  const nodes = [{ ...hub!, position: { x: -hub!.width! / 2, y: -hub!.height! / 2 } }, ...placed];
+  const center = (node: CardNode): Point => ({ x: node.position.x + node.width! / 2, y: node.position.y + node.height! / 2 });
+  const pairs = new Map<string, Link[]>();
+  for (const link of links) {
+    const pair = [link.source, link.target].sort().join("\n");
+    pairs.set(pair, [...(pairs.get(pair) ?? []), link]);
+  }
+  const edges = links.map((link): RouteEdge => {
+    const siblings = pairs.get([link.source, link.target].sort().join("\n"))!;
+    const offset = (siblings.indexOf(link) - (siblings.length - 1) / 2) * 16;
+    const source = nodes.find(node => node.id === link.source)!;
+    const target = nodes.find(node => node.id === link.target)!;
+    const spoke = source.id === hub!.id ? target : target.id === hub!.id ? source : undefined;
+    const data = { status: link.status, labelWidth: link.label ? Math.ceil(textMeasure()(link.label)) : 0 };
+    if (!spoke) {
+      const start = center(source);
+      const end = center(target);
+      return { ...link, type: "route", data: { ...data, path: `M ${start.x} ${start.y} L ${end.x} ${end.y}`, x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 } };
+    }
+    const { side, relativeY } = rows.get(spoke.id)!;
+    const hubPort = { x: side * hub!.width! / 2, y: relativeY * (hub!.height! / 2 - 24) + offset };
+    const spokePort = { x: center(spoke).x - side * spoke.width! / 2, y: center(spoke).y + offset };
+    const [start, end] = source.id === hub!.id ? [hubPort, spokePort] : [spokePort, hubPort];
+    const reach = side * Math.abs(end.x - start.x) / 2 * (source.id === hub!.id ? 1 : -1);
+    const path = `M ${start.x} ${start.y} C ${start.x + reach} ${start.y} ${end.x - reach} ${end.y} ${end.x} ${end.y}`;
+    return { ...link, type: "route", data: { ...data, path, x: (start.x + end.x) / 2, y: (start.y + end.y) / 2 } };
+  });
+  return { nodes, edges, bounds: bounds(corners(nodes)) };
+}
+
+async function layeredLayout(cards: CardNode[], links: Link[], direction: "right" | "down"): Promise<Placement> {
+  const { default: ELK } = await import("elkjs/lib/elk.bundled.js");
+  const result: ElkNode = await new ELK().layout({
+    id: "root", layoutOptions: { "elk.algorithm": "layered", "elk.direction": direction === "right" ? "RIGHT" : "DOWN", "elk.edgeRouting": "ORTHOGONAL", "elk.spacing.nodeNode": "52", "elk.layered.spacing.nodeNodeBetweenLayers": "94" },
+    children: cards.map(({ id, width, height }) => ({ id, width, height })),
+    edges: links.filter(edge => edge.kind !== "return").map(({ id, source, target, label }) => ({ id, sources: [source], targets: [target], ...(label ? { labels: [{ text: label, width: Math.max(40, Math.ceil(textMeasure()(label))), height: 24 }] } : {}) })),
+  });
+  const nodes = cards.map((card, index) => ({ ...card, position: { x: result.children![index]!.x!, y: result.children![index]!.y! } }));
+  const extraPoints: Point[] = [];
+  let lane = Math.max(...nodes.map(node => node.position.x + node.width!)) + 48;
+  const edges: RouteEdge[] = links.map((edge) => {
+    if (edge.kind === "return") {
+      const source = nodes.find(node => node.id === edge.source)!;
+      const target = nodes.find(node => node.id === edge.target)!;
+      const start = { x: source.position.x + source.width!, y: source.position.y + source.height! * (edge.source === edge.target ? 2 / 3 : 1 / 2) };
+      const end = { x: target.position.x + target.width!, y: target.position.y + target.height! * (edge.source === edge.target ? 1 / 3 : 1 / 2) };
+      const labelWidth = edge.label ? Math.ceil(textMeasure()(edge.label)) : 0;
+      const x = lane;
+      const y = (start.y + end.y) / 2;
+      const path = `M ${start.x} ${start.y} L ${lane} ${start.y} L ${lane} ${end.y} L ${end.x} ${end.y}`;
+      extraPoints.push(start, end, { x: lane, y: start.y }, { x: lane, y: end.y }, { x: lane + 16, y: y + labelWidth / 2 + 8 }, { x: lane - 16, y: y - labelWidth / 2 - 8 });
+      lane += 32;
+      return { ...edge, type: "route", data: { path, x, y, rotated: true, labelWidth, status: edge.status } };
+    }
+    const route = result.edges!.find(route => route.id === edge.id)!;
+    if (!route.sections?.length) throw new Error("Für eine Verbindung fehlt die automatische Linienführung.");
+    const path = route.sections.map((section) => [section.startPoint, ...(section.bendPoints ?? []), section.endPoint].map((point, index) => `${index ? "L" : "M"} ${point.x} ${point.y}`).join(" ")).join(" ");
+    const section = route.sections[0]!;
+    const label = route.labels?.[0];
+    return { ...edge, type: "route", data: { path, status: edge.status, x: label?.x === undefined ? (section.startPoint.x + section.endPoint.x) / 2 : label.x + (label.width ?? 0) / 2, y: label?.y === undefined ? (section.startPoint.y + section.endPoint.y) / 2 : label.y + (label.height ?? 0) / 2 } };
+  });
+  const points = [...corners(nodes), ...extraPoints];
+  for (const edge of result.edges ?? []) {
+    for (const section of edge.sections ?? []) points.push(section.startPoint, ...(section.bendPoints ?? []), section.endPoint);
+    for (const label of edge.labels ?? []) {
+      if (label.x !== undefined && label.y !== undefined) points.push({ x: label.x - 8, y: label.y - 8 }, { x: label.x + (label.width ?? 0) + 8, y: label.y + (label.height ?? 0) + 8 });
+    }
+  }
+  return { nodes, edges, bounds: bounds(points) };
+}
+
+const FlowDiagramRenderer = lazy(() => import("./FlowDiagramRenderer"));
+
+const flowSurface = "w-full min-w-0 overflow-hidden bg-transparent text-[16px]/[1.5] text-foreground [&>p]:p-4 [&_[role=alert]]:text-destructive data-[viewport=fit-width]:flex-none data-[viewport=fit]:h-full data-[viewport=fit]:min-h-0 data-[viewport=fit]:flex-auto";
+
+export function FlowDiagram(props: FlowDiagramProps) {
+  const inputKey = JSON.stringify([props.nodes, props.edges, props.direction, props.height, props.viewport, props.detailLevel, props.layout]);
+  const prepared = useMemo(() => {
+    try { return { graph: prepare(props) }; }
+    catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
+  }, [inputKey]);
+  const graph = prepared.graph;
+  const [layout, setLayout] = useState<Layout>();
+  const key = graph?.key;
+  useEffect(() => {
+    if (!graph || graph.cards.length === 0) return;
+    let current = true;
+    void (async () => {
+      const placement = graph.layout === "star" ? starLayout(graph.cards, graph.links) : await layeredLayout(graph.cards, graph.links, graph.direction);
+      if (current) setLayout({ key: graph.key, ...placement });
+    })().catch((error: unknown) => { if (current) setLayout({ key: graph.key, nodes: [], edges: [], error: error instanceof Error ? error.message : String(error) }); });
+    return () => { current = false; };
+  }, [key]);
+  const active = layout?.key === key ? layout : undefined;
+  const error = prepared.error ?? active?.error;
+  const cards = active?.nodes.map((node, index) => ({ ...node, data: { ...graph!.cards[index]!.data, onAction: props.onAction } })) ?? [];
+  const viewport = props.viewport ?? "interactive";
+  return <section aria-label={props.label} className={cn(flowSurface, props.className)} data-viewport={viewport} style={{ height: viewport !== "interactive" ? undefined : Number.isFinite(props.height) && props.height! > 0 ? props.height : 360 }}>
+    {error ? <p role="alert">Das Diagramm konnte nicht angezeigt werden: {error}</p>
+      : graph?.cards.length === 0 ? <p role="status">Keine Knoten vorhanden.</p>
+        : !active ? <p role="status">Diagramm wird geladen ...</p>
+          : <Suspense fallback={<p role="status">Diagramm wird geladen ...</p>}><FlowDiagramRenderer key={key} mode={viewport} bounds={active.bounds!} nodes={cards} edges={active.edges.map((edge, index) => ({ ...edge, label: graph!.links[index]!.label, data: { ...edge.data!, status: graph!.links[index]!.status } }))} /></Suspense>}
+  </section>;
+}

package/plugins/ragents.actor-programs/client-ui/FlowDiagramRenderer.tsx

@@ -0,0 +1,85 @@
+import React, { useEffect, useRef, useState } from "react";
+import { BaseEdge, Controls, Handle, MarkerType, Position, ReactFlow, type EdgeProps, type NodeProps } from "@xyflow/react";
+import { Button, cn } from "../../../apps/web/src/ui";
+import type { CardNode, GraphBounds, RouteEdge } from "./FlowDiagram";
+
+const statusLabels = { pending: "Ausstehend", active: "Aktiv", done: "Fertig", blocked: "Blockiert", skipped: "Übersprungen" };
+const edgeColors = { pending: "var(--muted-foreground)", active: "var(--info)", done: "var(--success)", blocked: "var(--destructive)" };
+const edgeClasses = {
+  pending: "[--xy-edge-stroke:var(--muted-foreground)] [stroke-dasharray:4_6]",
+  active: "[--xy-edge-stroke:var(--info)] [stroke-dasharray:9_5] animate-edge-flow motion-reduce:animate-none",
+  done: "[--xy-edge-stroke:var(--success)]",
+  blocked: "[--xy-edge-stroke:var(--destructive)]",
+};
+const statusIconClass = "size-[18px] flex-none text-muted-foreground data-[status=active]:text-info data-[status=done]:text-success data-[status=blocked]:text-destructive in-data-[running=true]:data-[status=active]:animate-spin in-data-[running=true]:data-[status=active]:[animation-duration:1.3s] in-data-[running=true]:data-[status=active]:motion-reduce:animate-none";
+const cardStatusTones = "[--flow-status:var(--muted-foreground)] data-[status=active]:[--flow-status:var(--info)] data-[status=done]:[--flow-status:var(--success)] data-[status=blocked]:[--flow-status:var(--destructive)]";
+
+function StatusIcon({ status, className }: { status: keyof typeof statusLabels; className?: string }) {
+  return <svg className={cn(statusIconClass, className)} data-status={status} role="img" aria-label={statusLabels[status]} viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" strokeLinejoin="round">
+    {status === "pending" ? <circle cx="10" cy="10" r="7" />
+      : status === "done" ? <path d="M4 10 L8 14 L16 5" />
+        : status === "active" ? <path d="M10 3 A7 7 0 1 1 3 10" />
+          : status === "blocked" ? <><circle cx="10" cy="10" r="7" /><path d="M10 6 V10 M10 14 H10.01" /></>
+            : <path d="M4 10 H16" />}
+  </svg>;
+}
+
+function Card({ data }: NodeProps<CardNode>) {
+  return <div className={cn(cardStatusTones, "pointer-events-auto h-full overflow-hidden rounded-[12px] border border-[color-mix(in_srgb,var(--flow-status)_60%,var(--border))] bg-card text-[16px]/[24px] shadow-[0_3px_9px_#49384e20] data-[running=true]:animate-ring-pulse data-[running=true]:motion-reduce:animate-none")}
+    data-status={data.status ?? "pending"} data-kind={data.kind} data-detail-level={data.detailLevel} data-running={data.status === "active" && data.running === true}>
+    <Handle type="target" position={data.direction === "right" ? Position.Left : Position.Top} />
+    <div className="relative rounded-t-[11px] bg-[color-mix(in_srgb,var(--flow-status)_12%,var(--card))] px-[17px] py-[15px] in-data-[detail-level=summary]:py-[10px]">
+      <h3 className="font-semibold whitespace-pre" title={[data.label, statusLabels[data.status ?? "pending"], data.detail].filter(Boolean).join("\n")}>{data.labelLines}</h3>
+      <span className="mt-[4px] flex h-[24px] w-max items-center gap-[7px] rounded-[12px] bg-[color-mix(in_srgb,var(--flow-status)_23%,var(--card))] px-[7px] font-semibold text-[var(--flow-status)]"><StatusIcon status={data.status ?? "pending"} />{statusLabels[data.status ?? "pending"]}</span>
+    </div>
+    {data.detailLines !== undefined && <div className="border-t border-border px-[17px] pt-[11px] pb-[12px] whitespace-pre">{data.detailLines}</div>}
+    {data.itemLines.length > 0 && <ul>{data.itemLines.map((item, index) => <li className="group border-t border-border px-[17px] pt-[11px] pb-[12px] whitespace-pre in-data-[detail-level=summary]:pt-[5px] in-data-[detail-level=summary]:pb-[6px]"
+      key={index} data-status={item.status ?? "pending"} title={[item.label, statusLabels[item.status ?? "pending"], item.detail].filter(Boolean).join("\n")}>
+      <div className="flex items-start gap-[10px] font-semibold in-data-[detail-level=summary]:font-normal"><StatusIcon className="mt-[3px]" status={item.status ?? "pending"} /><span>{item.labelLines}</span></div>
+      {data.detailLevel !== "summary" && <div className="text-muted-foreground group-data-[status=active]:text-info group-data-[status=done]:text-success group-data-[status=blocked]:text-destructive">{statusLabels[item.status ?? "pending"]}</div>}
+      {item.detailLines !== undefined && <div>{item.detailLines}</div>}
+    </li>)}</ul>}
+    {data.actions !== undefined && data.actions.length > 0 && <div className="nodrag nopan flex flex-wrap gap-2 border-t border-border px-[17px] py-[10px]">{data.actions.map((action) =>
+      <Button key={action.id} disabled={action.disabled} onClick={() => data.onAction?.(data.id, action.id)} size="sm" variant={action.primary ? "default" : "outline"}>{action.label}</Button>)}</div>}
+    <Handle type="source" position={data.direction === "right" ? Position.Right : Position.Bottom} />
+  </div>;
+}
+function Route({ id, data, label, markerEnd }: EdgeProps<RouteEdge>) {
+  if (!data) return null;
+  return <><BaseEdge className={data.status ? edgeClasses[data.status] : undefined} data-status={data.status} id={id} path={data.path} markerEnd={markerEnd} label={data.rotated ? undefined : label} labelX={data.x} labelY={data.y} />
+    {data.rotated && label && <g data-kind="return" transform={`translate(${data.x} ${data.y}) rotate(-90)`}>
+      <rect className="fill-background" x={-(data.labelWidth ?? 0) / 2 - 4} y={-12} width={(data.labelWidth ?? 0) + 8} height={24} rx={4} />
+      <text className="fill-foreground text-[16px]" textAnchor="middle" dominantBaseline="central">{label}</text>
+    </g>}
+  </>;
+
+}
+const nodeTypes = { card: Card };
+const edgeTypes = { route: Route };
+const diagramScale = 0.8;
+
+export default function FlowDiagramRenderer({ nodes, edges, bounds, mode }: { nodes: CardNode[]; edges: RouteEdge[]; bounds: GraphBounds; mode: "interactive" | "fit-width" | "fit" }) {
+  const host = useRef<HTMLDivElement>(null);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const fitted = mode !== "interactive";
+  useEffect(() => {
+    if (!fitted || !host.current) return;
+    const element = host.current;
+    const measure = () => setSize({ width: element.clientWidth, height: element.clientHeight });
+    const observer = new ResizeObserver(measure);
+    observer.observe(element);
+    measure();
+    return () => observer.disconnect();
+  }, [fitted]);
+  const zoom = size.width > 0 ? Math.min(diagramScale, size.width / bounds.width, mode === "fit" ? size.height / bounds.height : Infinity) : diagramScale;
+  const offsetX = Math.max(0, size.width - bounds.width * zoom) / 2;
+  const offsetY = mode === "fit" ? Math.max(0, size.height - bounds.height * zoom) / 2 : 0;
+  return <div ref={host} className="w-full min-w-0" style={{ height: mode === "fit-width" ? Math.ceil(bounds.height * zoom) : "100%" }}><ReactFlow
+    viewport={fitted ? { x: offsetX - bounds.x * zoom, y: offsetY - bounds.y * zoom, zoom } : undefined}
+    zoomOnScroll={!fitted} zoomOnPinch={!fitted} zoomOnDoubleClick={!fitted} panOnDrag={!fitted} panOnScroll={false}
+    preventScrolling={!fitted} disableKeyboardA11y={fitted} autoPanOnNodeFocus={false}
+    zoomActivationKeyCode={fitted ? null : "Meta"} panActivationKeyCode={fitted ? null : "Space"}
+ ariaLabelConfig={{ "controls.zoomIn.ariaLabel": "Zoom vergrößern", "controls.zoomOut.ariaLabel": "Zoom verkleinern", "controls.fitView.ariaLabel": "Ansicht zentrieren" }} nodes={nodes} edges={edges.map(edge => ({ ...edge, markerEnd: { type: MarkerType.ArrowClosed, color: edgeColors[edge.data?.status ?? "pending"] } }))} nodeTypes={nodeTypes} edgeTypes={edgeTypes} nodesDraggable={false} nodesConnectable={false} elementsSelectable={false} nodesFocusable={false} edgesFocusable={false} fitView={!fitted} fitViewOptions={{ minZoom: diagramScale, maxZoom: diagramScale, padding: 0.15 }} minZoom={fitted ? zoom : 0.3} maxZoom={fitted ? zoom : 2} proOptions={{ hideAttribution: true }}>
+    {!fitted && <Controls showInteractive={false} fitViewOptions={{ minZoom: diagramScale, maxZoom: diagramScale }} />}
+  </ReactFlow></div>;
+}

package/plugins/ragents.actor-programs/client-ui/Form.tsx

@@ -0,0 +1,126 @@
+import React, { useId, useRef, useState, type FormEvent } from "react";
+import { Button, Checkbox, Field, FieldDescription, FieldError, FieldLabel, Input, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Textarea } from "../../../apps/web/src/ui";
+import type { FormErrors, FormField, FormProps, FormValue, FormValues } from "./form-contracts";
+
+export function validateForm(fields: readonly FormField[], values: FormValues, validate?: FormProps["validate"]): FormErrors {
+  const errors: Record<string, string> = {};
+  for (const field of fields) {
+    if (field.disabled) continue;
+    const value = values[field.id];
+    const empty = value === undefined || value === null || typeof value === "string" && value.trim() === "";
+    if (field.required && (empty || field.type === "checkbox" && value !== true)) {
+      errors[field.id] = "Bitte ausfüllen.";
+    } else if (!empty) {
+      if (field.type === "number") {
+        if (typeof value !== "number" || !Number.isFinite(value)) errors[field.id] = "Bitte eine gültige Zahl eingeben.";
+        else if (field.min !== undefined && value < field.min) errors[field.id] = `Mindestens ${field.min}.`;
+        else if (field.max !== undefined && value > field.max) errors[field.id] = `Höchstens ${field.max}.`;
+      } else if (field.type === "checkbox") {
+        if (typeof value !== "boolean") errors[field.id] = "Bitte eine gültige Auswahl treffen.";
+      } else if (typeof value !== "string") {
+        errors[field.id] = "Bitte Text eingeben.";
+      } else if (field.type === "select" && !field.options.some((option) => option.value === value)) {
+        errors[field.id] = "Bitte einen angebotenen Wert auswählen.";
+      }
+    }
+  }
+  return { ...validate?.(values), ...errors };
+}
+
+export function Form({ title, fields, values, onChange, onSubmit, validate, submitLabel = "Speichern", disabled = false, readOnly = false }: FormProps) {
+  const prefix = useId();
+  const form = useRef<HTMLFormElement>(null);
+  const sending = useRef(false);
+  const [pending, setPending] = useState(false);
+  const [errors, setErrors] = useState<FormErrors>({});
+  const [error, setError] = useState<string>();
+  const ids = new Set(fields.map((field) => field.id));
+  if (ids.size !== fields.length || fields.some((field) => !field.id.trim())) throw new Error("Formularfelder benötigen eindeutige, nicht leere IDs.");
+
+  const change = (field: FormField, value: FormValue) => {
+    if (sending.current || disabled || readOnly || field.disabled || field.readOnly) return;
+    setErrors((current) => Object.fromEntries(Object.entries(current).filter(([id]) => id !== field.id)));
+    setError(undefined);
+    onChange({ ...values, [field.id]: value }, field.id);
+  };
+  const submit = async (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    if (!onSubmit || sending.current || disabled || readOnly) return;
+    setError(undefined);
+    try {
+      const nextErrors = validateForm(fields, values, validate);
+      setErrors(nextErrors);
+      if (Object.values(nextErrors).some(Boolean)) {
+        const index = fields.findIndex((field) => nextErrors[field.id]);
+        form.current?.querySelector<HTMLElement>(`[data-field-index="${index}"] input, [data-field-index="${index}"] textarea, [data-field-index="${index}"] button`)?.focus();
+        return;
+      }
+      sending.current = true;
+      setPending(true);
+      await onSubmit({ ...values });
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally {
+      sending.current = false;
+      setPending(false);
+    }
+  };
+  return (
+    <form aria-label={title ?? "Formular"} aria-busy={pending} className="flex min-w-0 flex-col gap-4" noValidate onSubmit={(event) => void submit(event)} ref={form}>
+      {title && <h2 className="text-base font-semibold">{title}</h2>}
+      {fields.map((field, index) => {
+        const id = `${prefix}-${index}`;
+        const fieldError = errors[field.id];
+        const locked = readOnly || field.readOnly;
+        const inactive = disabled || pending || field.disabled;
+        const describedBy = [field.hint && `${id}-hint`, fieldError && `${id}-error`].filter(Boolean).join(" ") || undefined;
+        const value = values[field.id];
+        const label = `${field.label}${field.required ? " *" : ""}`;
+        const shared = { id, disabled: inactive, readOnly: locked, required: field.required, "aria-invalid": Boolean(fieldError), "aria-describedby": describedBy };
+        const hint = field.hint && <FieldDescription id={`${id}-hint`}>{field.hint}</FieldDescription>;
+        const problem = fieldError && <FieldError id={`${id}-error`}>{fieldError}</FieldError>;
+        if (field.type === "checkbox") {
+          return (
+            <Field data-disabled={inactive || locked} data-field-index={index} data-invalid={Boolean(fieldError)} key={field.id} orientation="horizontal">
+              <Checkbox {...shared} checked={value === true} disabled={inactive || locked} onCheckedChange={(checked) => change(field, checked)} />
+              <div className="flex flex-col gap-0.5">
+                <FieldLabel htmlFor={id}>{label}</FieldLabel>
+                {hint}
+                {problem}
+              </div>
+            </Field>
+          );
+        }
+        if (field.type === "select") {
+          return (
+            <Field data-disabled={inactive} data-field-index={index} data-invalid={Boolean(fieldError)} key={field.id}>
+              <FieldLabel htmlFor={id}>{label}</FieldLabel>
+              {locked
+                ? <p className="text-sm">{field.options.find((option) => option.value === value)?.label ?? String(value ?? "")}</p>
+                : <Select disabled={inactive} items={field.options} value={typeof value === "string" ? value : ""} onValueChange={(next) => { if (next !== null) change(field, next); }}>
+                  <SelectTrigger aria-describedby={describedBy} aria-invalid={Boolean(fieldError)} className="w-full" id={id}><SelectValue /></SelectTrigger>
+                  <SelectContent>{field.options.map((option) => <SelectItem key={option.value} value={option.value}>{option.label}</SelectItem>)}</SelectContent>
+                </Select>}
+              {hint}
+              {problem}
+            </Field>
+          );
+        }
+        return (
+          <Field data-disabled={inactive} data-field-index={index} data-invalid={Boolean(fieldError)} key={field.id}>
+            <FieldLabel htmlFor={id}>{label}</FieldLabel>
+            {field.type === "textarea"
+              ? <Textarea {...shared} onChange={(event) => change(field, event.target.value)} placeholder={field.placeholder} rows={field.rows ?? 2} value={typeof value === "string" ? value : ""} />
+              : field.type === "number"
+                ? <Input {...shared} max={field.max} min={field.min} onChange={(event) => change(field, Number.isNaN(event.target.valueAsNumber) ? null : event.target.valueAsNumber)} placeholder={field.placeholder} step={field.step ?? "any"} type="number" value={typeof value === "number" && Number.isFinite(value) ? value : ""} />
+                : <Input {...shared} onChange={(event) => change(field, event.target.value)} placeholder={field.placeholder} type="text" value={typeof value === "string" ? value : ""} />}
+            {hint}
+            {problem}
+          </Field>
+        );
+      })}
+      {error && <FieldError>{error}</FieldError>}
+      {onSubmit && !readOnly && <Button className="self-start" disabled={disabled || pending} type="submit">{pending ? "Wird gespeichert ..." : submitLabel}</Button>}
+    </form>
+  );
+}

package/plugins/ragents.actor-programs/client-ui/Layout.tsx

@@ -0,0 +1,27 @@
+import React, { useId } from "react";
+import { cn } from "../../../apps/web/src/ui";
+import type { AppLayoutProps, GridProps, LayoutGap, StackProps } from "./layout-contracts";
+
+const gaps: Record<LayoutGap, string> = { small: "gap-1.5", normal: "gap-3", large: "gap-5" };
+
+export function AppLayout({ title, description, actions, children, fill = false }: AppLayoutProps) {
+  const titleId = useId();
+  return <section aria-labelledby={title ? titleId : undefined} className={cn("flex min-w-0 flex-col gap-4 p-4 text-sm break-words [#root>&]:p-0", fill && "h-full min-h-0")} data-fill={fill}>
+    {(title || description) && <header className="flex min-w-0 flex-none flex-col gap-1">
+      {title && <h1 className="text-xl leading-tight font-semibold" id={titleId}>{title}</h1>}
+      {description && <div className="text-muted-foreground">{description}</div>}
+    </header>}
+    <div className={cn("min-w-0", fill && "-m-1 min-h-0 flex-1 overflow-auto p-1 [scrollbar-gutter:stable]")}>{children}</div>
+    {actions && <footer className="flex min-w-0 flex-none flex-wrap items-center gap-2">{actions}</footer>}
+  </section>;
+}
+
+export function Stack({ children, gap = "normal", direction = "column" }: StackProps) {
+  return <div className={cn("flex min-w-0 *:max-w-full *:min-w-0", gaps[gap], direction === "row" ? "flex-row flex-wrap items-center" : "flex-col")}>{children}</div>;
+}
+
+export function Grid({ children, columns = 2, gap = "normal" }: GridProps) {
+  return <div className="@container min-w-0">
+    <div className={cn("grid grid-cols-1 items-start *:max-w-full *:min-w-0 @[520px]:grid-cols-2", gaps[gap], columns === 3 && "@[760px]:grid-cols-3")}>{children}</div>
+  </div>;
+}

package/plugins/ragents.actor-programs/client-ui/MessageList.tsx

@@ -0,0 +1,30 @@
+import React, { useMemo } from "react";
+import { cn } from "../../../apps/web/src/ui";
+import { ChatMessages } from "../../../apps/web/src/chat/ChatMessages";
+import type { Message } from "../../../apps/server/src/chat-events";
+import type { MessageListProps } from "./message-list-contracts";
+
+const hues = [212, 158, 28, 283, 350, 190, 95, 320, 55, 245];
+const senderColor = (sender: string): string => {
+  let hash = 0;
+  for (const character of sender) hash = (Math.imul(hash, 31) + character.codePointAt(0)!) >>> 0;
+  return `hsl(${hues[hash % hues.length]} 45% 42%)`;
+};
+
+export function MessageList({ messages, label = "Nachrichten", className, ...props }: MessageListProps) {
+  const rendered = useMemo(() => messages.map((message): Message => ({
+    key: message.key,
+    role: "assistant",
+    sender: message.sender,
+    text: message.text,
+    closed: true,
+    at: message.at,
+    attachments: message.attachments,
+    bubble: { label: message.sender, color: message.color ?? senderColor(message.sender), side: message.side ?? "start" },
+  })), [messages]);
+  return (
+    <section aria-label={label} className={cn("flex h-full min-h-0 w-full min-w-0 flex-col text-foreground", className)}>
+      <ChatMessages {...props} detailMode="off" messages={rendered} />
+    </section>
+  );
+}

package/plugins/ragents.actor-programs/client-ui/Viewers.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { Markdown } from "../../../apps/web/src/chat/Markdown";
+import { DiffCode } from "../../../apps/web/src/DiffCode";
+import { SourceCode } from "../../../apps/web/src/SourceCode";
+import { cn, Progress } from "../../../apps/web/src/ui";
+import type { DiffViewerProps, DocumentViewerProps, TaskProgressProps } from "./viewer-contracts";
+
+const taskLabels = { pending: "Offen", running: "In Arbeit", done: "Erledigt", error: "Fehlgeschlagen", skipped: "Übersprungen" };
+const taskTones = { pending: "text-muted-foreground", running: "text-primary", done: "text-muted-foreground", error: "text-destructive", skipped: "text-muted-foreground" };
+
+export function TaskProgress({ title = "Aufgaben", tasks, showProgress = true }: TaskProgressProps) {
+  const completed = tasks.filter((task) => task.status === "done" || task.status === "skipped").length;
+  return <section aria-label={title} className="min-w-0 text-sm">
+    <h3 className="mb-2 text-[15px] font-semibold">{title}</h3>
+    {showProgress && tasks.length > 0 && <div className="mb-2 flex flex-wrap items-center gap-2 text-muted-foreground">
+      <Progress aria-label={title} className="min-w-20 flex-1" max={tasks.length} value={completed} />
+      <span>{completed} von {tasks.length} abgeschlossen</span>
+    </div>}
+    {!tasks.length && <p>Noch keine Aufgaben.</p>}
+    <ol className="divide-y">{tasks.map((task) => <li className="py-1.5" data-status={task.status} key={task.id}>
+      <div className="flex justify-between gap-3"><strong>{task.label}</strong><span className={cn("whitespace-nowrap", taskTones[task.status])}>{taskLabels[task.status]}</span></div>
+      {task.description && <p className="mt-1 text-muted-foreground">{task.description}</p>}
+    </li>)}</ol>
+  </section>;
+}
+
+export function DocumentViewer({ title, content, format = "text", language, filename }: DocumentViewerProps) {
+  return <section aria-label={title ?? filename ?? "Dokument"} className="min-w-0 text-sm">
+    {(title || filename) && <h3 className="mb-2 text-[15px] font-semibold">{title ?? filename}</h3>}
+    {format === "markdown" ? <Markdown text={content} />
+      : format === "code" ? <SourceCode content={content} language={language} path={filename ?? ""} />
+        : <pre className="m-0 font-[inherit] break-words whitespace-pre-wrap">{content}</pre>}
+  </section>;
+}
+
+export function DiffViewer({ title = "Änderungen", patch, emptyText = "Keine Änderungen.", language, filename }: DiffViewerProps) {
+  return <section aria-label={title} className="min-w-0 text-sm">
+    <h3 className="mb-2 text-[15px] font-semibold">{title}</h3>
+    {!patch ? <p>{emptyText}</p> : <div className="max-w-full overflow-auto rounded-lg border"><DiffCode content={patch} emptyText={emptyText} language={language} path={filename} /></div>}
+  </section>;
+}

package/plugins/ragents.actor-programs/client-ui/WorkflowDiagram.tsx

@@ -0,0 +1,14 @@
+import React, { useMemo } from "react";
+import { workflowGraph } from "../workflow/index";
+import { FlowDiagram } from "./FlowDiagram";
+import type { WorkflowDiagramProps } from "./workflow-diagram-contracts";
+
+export function WorkflowDiagram({ definition, state, ...props }: WorkflowDiagramProps) {
+  const projection = useMemo(() => {
+    try { return { graph: workflowGraph(definition, state) }; }
+    catch (error) { return { error: error instanceof Error ? error.message : String(error) }; }
+  }, [definition, state]);
+  return projection.graph
+    ? <FlowDiagram direction="down" viewport="fit-width" {...props} {...projection.graph} />
+    : <section aria-label={props.label} className={props.className}><p role="alert">Der Ablauf konnte nicht angezeigt werden: {projection.error}</p></section>;
+}