@eventcatalog/core 5.0.0-beta.4 → 5.0.0-beta.6

package/eventcatalog/src/features/studio/hooks/use-studio-flow.ts

@@ -0,0 +1,423 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import * as Y from 'yjs';
+import { HocuspocusProvider } from '@hocuspocus/provider';
+import { Awareness } from 'y-protocols/awareness';
+import {
+  applyEdgeChanges,
+  applyNodeChanges,
+  type Connection,
+  type Edge,
+  type EdgeChange,
+  type Node,
+  type NodeChange,
+  type XYPosition,
+} from '@xyflow/react';
+import {
+  addNodes,
+  buildNode,
+  canvasDocumentName,
+  connectNodes,
+  deleteEdges,
+  deleteNodes as deleteNodesInDoc,
+  fitGroupToChildren,
+  getCanvasMaps,
+  moveNode,
+  readMeta,
+  resizeNode,
+  setMeta,
+  setNodeParent,
+  updateNodeData as updateNodeDataInDoc,
+} from '../canvas-doc';
+import { applyLayout } from '../agent-choreography';
+import { keepDragged, LOCAL_EDGE_KEYS, LOCAL_NODE_KEYS, patchShared, withPositions } from '../flow-state';
+import { findGroupAtPoint, toRelativePosition } from '../grouping';
+import type { LayoutResult } from '../layout';
+import { getNodeDefinition } from '../node-types';
+import { startToolSync, type ToolSync } from '../tool-sync';
+import { createPresenceSender, type PresenceSender } from './presence-sender';
+import { createPresenceStore, type PresenceStore } from './presence-store';
+
+export type { Peer } from './presence-store';
+
+/** How long the WebSocket gets to connect before a view that can sync through tool calls switches to them */
+const SOCKET_TIMEOUT_MS = 4000;
+/**
+ * After someone drops what they were dragging, how long until it goes back to where the document has it, if the
+ * drop doesn't arrive (they left mid-drag). The drop normally arrives first, or within a few milliseconds.
+ */
+const DROP_SETTLE_MS = 500;
+
+/**
+ * Changes made here that are already shown here (nodes dragged and resized with React Flow): the document
+ * observers skip them, and undo includes them
+ */
+const LOCAL_ORIGIN = Symbol('studio-local');
+/** Changes an agent working through this tab (WebMCP) makes: synced like anyone's, and not in the user's undo */
+export const BROWSER_AGENT_ORIGIN = Symbol('studio-browser-agent');
+
+export type Status = 'connecting' | 'connected' | 'disconnected';
+export type Transport = 'websocket' | 'tools';
+
+type Shared = { doc: Y.Doc; awareness: Awareness; undoManager: Y.UndoManager; sender: PresenceSender };
+
+/**
+ * A React Flow design kept in a Yjs document (one map of nodes, one of edges), synced through Hocuspocus.
+ * Presence (who is here, their pointer and what they have selected) goes over Yjs awareness, in a store
+ * (see presence-store) rather than React state.
+ *
+ * Nodes being dragged go to everyone with our presence (with the pointer, about 30 times a second), and only
+ * where they're dropped is saved in the document: one change per drag, so the document doesn't grow with every
+ * step of every drag, and undo takes back the whole drag. Others show where we're dragging them as we do.
+ */
+export function useStudioFlow({
+  canvasId,
+  socketUrl,
+  name,
+  color,
+  syncViaTools,
+  onLayout,
+}: {
+  canvasId: string;
+  /** e.g. wss://catalog.example.com/_eventcatalog/studio */
+  socketUrl: string;
+  name: string;
+  color: string;
+  /** Sync through MCP tool calls when the WebSocket can't connect (e.g. inside a chat's sandbox) */
+  syncViaTools?: ToolSync;
+  /** Someone laid the canvas out (us included): called as the new positions arrive, so they can glide there */
+  onLayout?: () => void;
+}) {
+  const sharedRef = useRef<Shared | null>(null);
+  const [nodes, setNodes] = useState<Node[]>([]);
+  const [edges, setEdges] = useState<Edge[]>([]);
+  const [status, setStatus] = useState<Status>('connecting');
+  const [presence, setPresence] = useState<PresenceStore | null>(null);
+  const [clientId, setClientId] = useState<number | null>(null);
+  // Exposed so other shared state (e.g. comments) can live in the same document
+  const [doc, setDoc] = useState<Y.Doc | null>(null);
+  const [history, setHistory] = useState({ canUndo: false, canRedo: false });
+  const [title, setTitle] = useState<string | undefined>();
+  const [transport, setTransport] = useState<Transport>('websocket');
+  const user = useRef({ name, color });
+  user.current = { name, color };
+  const onLayoutRef = useRef(onLayout);
+  onLayoutRef.current = onLayout;
+
+  useEffect(() => {
+    // A new connection starts from what the server has. Clear anything left from a previous one,
+    // since an empty document never fires an update that would remove it.
+    setNodes([]);
+    setEdges([]);
+
+    const doc = new Y.Doc();
+    const { nodes: yNodes, edges: yEdges, threads: yThreads, meta: yMeta } = getCanvasMaps(doc);
+    const syncMeta = (event: Y.YMapEvent<unknown>) => {
+      setTitle(readMeta(doc).title);
+      if (event.keysChanged.has('layoutAt')) onLayoutRef.current?.();
+    };
+    yMeta.observe(syncMeta);
+    setTitle(undefined);
+    // One presence for whichever connection is used
+    const awareness = new Awareness(doc);
+    awareness.setLocalStateField('user', user.current);
+    const presenceStore = createPresenceStore(awareness);
+    setPresence(presenceStore);
+    const sender = createPresenceSender(awareness);
+    let socketConnected = false;
+    let stopToolSync: (() => void) | undefined;
+    const provider = new HocuspocusProvider({
+      url: socketUrl,
+      name: canvasDocumentName(canvasId),
+      document: doc,
+      awareness,
+      onStatus: ({ status }) => {
+        if (status === 'connected') socketConnected = true;
+        socketStatus = status as Status;
+        if (!stopToolSync) setStatus(status as Status);
+      },
+    });
+    let socketStatus: Status = 'connecting';
+    setTransport('websocket');
+
+    // Back online, or back on the tab: reconnect now rather than when the next retry is due
+    const reconnect = () => {
+      if (!stopToolSync && socketStatus === 'disconnected') void provider.connect();
+    };
+    // Away from the tab: our pointer goes from everyone's canvas
+    const onVisibilityChange = () => {
+      if (document.visibilityState === 'visible') return reconnect();
+      sender.send({ pointer: null });
+      sender.flush();
+    };
+    window.addEventListener('online', reconnect);
+    document.addEventListener('visibilitychange', onVisibilityChange);
+
+    // Some views can't open the WebSocket (a chat's sandbox may block it): sync through tool calls instead
+    const fallback = syncViaTools
+      ? setTimeout(() => {
+          if (socketConnected) return;
+          provider.disconnect();
+          setTransport('tools');
+          stopToolSync = startToolSync(doc, awareness, { canvasId, sync: syncViaTools, onStatus: setStatus });
+        }, SOCKET_TIMEOUT_MS)
+      : undefined;
+    // Undo only takes back your own changes: other people's arrive with the provider as origin, agents' with theirs
+    const undoManager = new Y.UndoManager([yNodes, yEdges, yThreads], {
+      captureTimeout: 500,
+      trackedOrigins: new Set([null, LOCAL_ORIGIN]),
+    });
+    const updateHistory = () =>
+      setHistory({ canUndo: undoManager.undoStack.length > 0, canRedo: undoManager.redoStack.length > 0 });
+    undoManager.on('stack-item-added', updateHistory);
+    undoManager.on('stack-item-popped', updateHistory);
+    undoManager.on('stack-cleared', updateHistory);
+    setHistory({ canUndo: false, canRedo: false });
+    sharedRef.current = { doc, awareness, undoManager, sender };
+    setClientId(doc.clientID);
+    setDoc(doc);
+
+    // Where others are dragging nodes, from their presence, until they drop them
+    let remoteMoves = new Map<string, XYPosition>();
+    const settling = new Set<ReturnType<typeof setTimeout>>();
+    const syncMoves = (_: unknown, origin: unknown) => {
+      if (origin === 'local') return;
+      const next = new Map<string, XYPosition>();
+      awareness.getStates().forEach((state, id) => {
+        if (id === doc.clientID || !state.moving) return;
+        Object.entries(state.moving as Record<string, XYPosition>).forEach(([nodeId, position]) => next.set(nodeId, position));
+      });
+      const moved = new Map([...next].filter(([id, { x, y }]) => remoteMoves.get(id)?.x !== x || remoteMoves.get(id)?.y !== y));
+      const dropped = [...remoteMoves.keys()].filter((id) => !next.has(id));
+      remoteMoves = next;
+      if (moved.size) setNodes((local) => withPositions(local, moved));
+      if (dropped.length === 0) return;
+      // The drop is saved in the document. If it doesn't arrive, back to where the document has it.
+      const settle = setTimeout(() => {
+        settling.delete(settle);
+        const saved = dropped.flatMap((id) => {
+          const node = remoteMoves.has(id) ? undefined : yNodes.get(id);
+          return node ? [[id, node.position] as const] : [];
+        });
+        setNodes((local) => withPositions(local, new Map(saved)));
+      }, DROP_SETTLE_MS);
+      settling.add(settle);
+    };
+    awareness.on('change', syncMoves);
+
+    // Only what changed is replaced, so React Flow re-renders just those nodes
+    const syncNodes = (event: Y.YMapEvent<Node>) => {
+      if (event.transaction.origin === LOCAL_ORIGIN) return;
+      // A node someone was dragging changed in the document: they dropped it there
+      event.keysChanged.forEach((id) => remoteMoves.delete(id));
+      setNodes((local) =>
+        keepDragged(
+          patchShared(local, event.keysChanged, (id) => yNodes.get(id), LOCAL_NODE_KEYS),
+          local
+        )
+      );
+    };
+    const syncEdges = (event: Y.YMapEvent<Edge>) => {
+      if (event.transaction.origin === LOCAL_ORIGIN) return;
+      setEdges((local) => patchShared(local, event.keysChanged, (id) => yEdges.get(id), LOCAL_EDGE_KEYS));
+    };
+    yNodes.observe(syncNodes);
+    yEdges.observe(syncEdges);
+
+    return () => {
+      clearTimeout(fallback);
+      settling.forEach(clearTimeout);
+      window.removeEventListener('online', reconnect);
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+      awareness.off('change', syncMoves);
+      sender.destroy();
+      stopToolSync?.();
+      yNodes.unobserve(syncNodes);
+      yEdges.unobserve(syncEdges);
+      yMeta.unobserve(syncMeta);
+      presenceStore.destroy();
+      undoManager.destroy();
+      provider.destroy();
+      doc.destroy();
+      sharedRef.current = null;
+      setDoc(null);
+      setPresence(null);
+    };
+  }, [canvasId, socketUrl, syncViaTools]);
+
+  useEffect(() => {
+    sharedRef.current?.awareness.setLocalStateField('user', { name, color });
+  }, [name, color]);
+
+  // Tell others what we have selected so they can see it
+  const selectionKey = useMemo(
+    () =>
+      nodes
+        .filter((node) => node.selected)
+        .map((node) => node.id)
+        .join(','),
+    [nodes]
+  );
+  useEffect(() => {
+    sharedRef.current?.sender.send({ selection: selectionKey ? selectionKey.split(',') : [] });
+  }, [selectionKey]);
+
+  const withDoc = <T>(fn: (doc: Y.Doc) => T, origin: unknown = null) => {
+    const doc = sharedRef.current?.doc;
+    return doc ? doc.transact(() => fn(doc), origin) : undefined;
+  };
+
+  // Where the nodes being dragged are, until they're dropped
+  const dragged = useRef(new Map<string, XYPosition>());
+  /** Saves where dragged nodes were dropped (in the transaction it's called in), and stops showing them as dragged */
+  const saveDrop = (doc: Y.Doc) => {
+    dragged.current.forEach((position, id) => moveNode(doc, id, position));
+    dragged.current.clear();
+    const shared = sharedRef.current;
+    shared?.sender.send({ moving: null });
+    // After the drop is in the document (it's sent as the transaction ends)
+    queueMicrotask(() => shared?.sender.flush());
+  };
+
+  const onNodesChange = useCallback((changes: NodeChange[]) => {
+    setNodes((local) => applyNodeChanges(changes, local));
+    let dropped = false;
+    const resized: { id: string; dimensions: { width: number; height: number } }[] = [];
+    for (const change of changes) {
+      if (change.type === 'position' && change.position) {
+        dragged.current.set(change.id, change.position);
+        if (!change.dragging) dropped = true;
+      }
+      // Containers resized with their handles
+      if (change.type === 'dimensions' && change.setAttributes && change.dimensions)
+        resized.push({ id: change.id, dimensions: change.dimensions });
+    }
+    // While dragging, nodes move here every frame and go to everyone with our presence; where they're dropped is saved
+    if (dropped) {
+      // Each drag is its own step to undo
+      sharedRef.current?.undoManager.stopCapturing();
+      withDoc(saveDrop, LOCAL_ORIGIN);
+    } else if (dragged.current.size) sharedRef.current?.sender.send({ moving: Object.fromEntries(dragged.current) });
+    if (resized.length) withDoc((doc) => resized.forEach(({ id, dimensions }) => resizeNode(doc, id, dimensions)), LOCAL_ORIGIN);
+    // Removing a node also removes what's in it, its edges, and moves its comments: those come back through the observers
+    const removed = changes.filter((change) => change.type === 'remove').map((change) => change.id);
+    if (removed.length) withDoc((doc) => deleteNodesInDoc(doc, removed));
+  }, []);
+
+  const onEdgesChange = useCallback((changes: EdgeChange[]) => {
+    setEdges((local) => applyEdgeChanges(changes, local));
+    const removed = changes.filter((change) => change.type === 'remove').map((change) => change.id);
+    if (removed.length) withDoc((doc) => deleteEdges(doc, removed));
+  }, []);
+
+  const onConnect = useCallback((connection: Connection) => {
+    withDoc((doc) => connectNodes(doc, connection));
+  }, []);
+
+  /**
+   * Add a node centred on a canvas position. `connect` gets the new node's id and the nodes already
+   * on the canvas, and returns edges to add with it (e.g. a catalog resource's relationships).
+   */
+  const insertNode = useCallback(
+    (type: string, data: Record<string, unknown>, center: XYPosition, connect?: (id: string, existing: Node[]) => Edge[]) => {
+      const built = buildNode(type, data, center);
+      withDoc((doc) => {
+        const existing = Array.from(getCanvasMaps(doc).nodes.values());
+        // Dropped on a container: it goes in it
+        const group = findGroupAtPoint(center, existing);
+        const node = group
+          ? { ...built, parentId: group.id, position: toRelativePosition(built.position, group.id, existing) }
+          : built;
+        addNodes(doc, [node], connect?.(node.id, existing) ?? []);
+        if (group) fitGroupToChildren(doc, group.id);
+      });
+      return built.id;
+    },
+    []
+  );
+
+  /** Add a node of a registry type, centred on a canvas position */
+  const addNode = useCallback(
+    (type: string, center: XYPosition) => {
+      const definition = getNodeDefinition(type);
+      return definition ? insertNode(type, definition.createData(), center) : undefined;
+    },
+    [insertNode]
+  );
+
+  const updateNodeData = useCallback(
+    (id: string, updater: (data: Record<string, unknown>) => Record<string, unknown>) =>
+      withDoc((doc) => updateNodeDataInDoc(doc, id, updater)),
+    []
+  );
+
+  const deleteNodes = useCallback((ids: string[]) => withDoc((doc) => deleteNodesInDoc(doc, ids)), []);
+
+  /** Moves nodes (and resizes containers) from a layout in one change, so it undoes in one go */
+  const applyPositions = useCallback((layout: LayoutResult) => withDoc((doc) => applyLayout(doc, layout)), []);
+
+  /** Adds ready-made nodes and edges (e.g. a container with what's in it) in one change */
+  const insertNodes = useCallback(
+    (nodes: Node[], edges: Edge[] = []) =>
+      withDoc((doc) => {
+        addNodes(doc, nodes, edges);
+        // Containers already on the canvas that got something new inside grow to fit it
+        const added = new Set(nodes.map((node) => node.id));
+        new Set(nodes.flatMap((node) => (node.parentId && !added.has(node.parentId) ? [node.parentId] : []))).forEach((groupId) =>
+          fitGroupToChildren(doc, groupId)
+        );
+      }),
+    []
+  );
+
+  /** Puts a node in a container (or takes it out), e.g. after it's dragged there */
+  const setParent = useCallback(
+    (nodeId: string, parentId: string | undefined) =>
+      withDoc((doc) => {
+        // Where it was dropped goes first, so it's moved into (or out of) the container from there
+        if (dragged.current.size) saveDrop(doc);
+        return setNodeParent(doc, nodeId, parentId);
+      }),
+    []
+  );
+
+  const rename = useCallback((next: string) => withDoc((doc) => setMeta(doc, { title: next || undefined })), []);
+
+  const undo = useCallback(() => sharedRef.current?.undoManager.undo(), []);
+  const redo = useCallback(() => sharedRef.current?.undoManager.redo(), []);
+
+  /** Our pointer on the canvas, for everyone (sent about 30 times a second, so call it on every move) */
+  const setPointer = useCallback((pointer: XYPosition | null) => {
+    sharedRef.current?.sender.send({ pointer });
+  }, []);
+
+  const setViewport = useCallback((viewport: { x: number; y: number; zoom: number }) => {
+    sharedRef.current?.sender.send({ viewport });
+  }, []);
+
+  return {
+    nodes,
+    edges,
+    status,
+    presence,
+    clientId,
+    doc,
+    onNodesChange,
+    onEdgesChange,
+    onConnect,
+    addNode,
+    insertNode,
+    updateNodeData,
+    deleteNodes,
+    applyPositions,
+    insertNodes,
+    setParent,
+    title,
+    rename,
+    transport,
+    undo,
+    redo,
+    ...history,
+    setPointer,
+    setViewport,
+  };
+}

package/eventcatalog/src/features/studio/layout.ts

@@ -0,0 +1,39 @@
+import type { Edge, Node, XYPosition } from '@xyflow/react';
+import { layoutWithElk } from '@eventcatalog/visualiser/layout';
+import { isGroupType } from './node-types';
+
+/**
+ * Lays a canvas out with the same ELK layout as EventCatalog's visualiser (left to right, edges routed
+ * around nodes, containers laid out with what's in them and sized to fit). Nodes are sized as rendered when
+ * they have been (in the browser), or by their type.
+ */
+export const layoutGraph = (nodes: Node[], edges: Edge[]) => layoutWithElk({ nodes, edges });
+
+/** The layout sizes containers with style.width/height; the canvas sizes them with width/height */
+export const withGroupSizes = (nodes: Node[]) =>
+  nodes.map((node) => {
+    const { width, height, ...style } = node.style ?? {};
+    if (typeof width !== 'number' || typeof height !== 'number') return node;
+    return { ...node, width, height, style };
+  });
+
+export type LayoutResult = Map<string, { position: XYPosition; size?: { width: number; height: number } }>;
+
+/**
+ * New positions (relative to their container, if they're in one) for the nodes on a canvas, and new sizes for
+ * containers. Only these are kept for the canvas people edit: the edge routes ELK draws would be out of date
+ * as soon as someone moves a node.
+ */
+export const getLayoutPositions = async (nodes: Node[], edges: Edge[]): Promise<LayoutResult> => {
+  if (nodes.length === 0) return new Map();
+  const laidOut = withGroupSizes((await layoutGraph(nodes, edges)).nodes);
+  return new Map(
+    laidOut.map((node) => [
+      node.id,
+      {
+        position: node.position,
+        ...(isGroupType(node.type) && node.width && node.height && { size: { width: node.width, height: node.height } }),
+      },
+    ])
+  );
+};

package/eventcatalog/src/features/studio/levels.ts

@@ -0,0 +1,216 @@
+import type { Edge, Node } from '@xyflow/react';
+import { getMessagesLabel } from '@eventcatalog/visualiser/layout';
+import { EDGE_MARKER, MESSAGE_COLLECTIONS } from './edges';
+import { GROUP_TYPES, isGroupType } from './node-types';
+
+/**
+ * Levels of detail, the same as EventCatalog's diagrams:
+ * - L1: domains, systems and how they relate (services folded into the system or domain that contains them)
+ * - L2: services and data stores, with messages and channels hidden (the nodes either side connected directly)
+ * - L3: everything, including messages and channels (the canvas people edit)
+ *
+ * What a domain or system contains is what sits inside it (as a container), or what it's connected to with
+ * "contains" (as a card, which catalog domains and systems get when their services are on the canvas).
+ */
+export type Level = 1 | 2 | 3;
+
+export const LEVELS: { level: Level; description: string }[] = [
+  { level: 1, description: 'Domains, systems and their relationships' },
+  { level: 2, description: 'Services and data stores' },
+  { level: 3, description: 'Everything, including messages and channels' },
+];
+
+// Domains and systems: as cards (what they contain is connected with "contains") or containers (it's inside)
+const CONTAINER_TYPES = new Set(['system', 'context-domain', GROUP_TYPES.system, GROUP_TYPES.domain]);
+const isSystem = (node: Node) => node.type === 'system' || node.type === GROUP_TYPES.system;
+const COLLAPSED_GROUP_SIZE = { width: 280, height: 110 };
+
+const isMessage = (node: Node) => !!MESSAGE_COLLECTIONS[node.type ?? ''];
+const isCarrier = (node: Node) => isMessage(node) || node.type === 'channel';
+const isContainer = (node: Node) => CONTAINER_TYPES.has(node.type ?? '');
+const messageName = (node: Node) => String((node.data as { message?: { name?: string } }).message?.name ?? node.id);
+
+/** What a node becomes at a level: kept (as itself or another node), carried through (messages, channels) or dropped */
+type Representative = { kind: 'node'; id: string } | { kind: 'carrier' } | { kind: 'drop' };
+
+/**
+ * Collapse a graph: each node is kept, replaced by another node (e.g. a service by its system),
+ * carried through (messages and channels: the nodes either side get connected directly) or dropped.
+ * Edges between the same two nodes are merged, labelled with the messages they carry.
+ */
+const collapseGraph = (nodes: Node[], edges: Edge[], representativeOf: (node: Node) => Representative) => {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  // Whether one node is inside another (e.g. a system in its domain): they're not connected, one holds the other
+  const isInside = (id: string, containerId: string) => {
+    for (let node = byId.get(id); node?.parentId; node = byId.get(node.parentId)) if (node.parentId === containerId) return true;
+    return false;
+  };
+  const representatives = new Map(nodes.map((node) => [node.id, representativeOf(node)]));
+  const outgoing = new Map<string, Edge[]>();
+  edges.forEach((edge) => outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]));
+
+  type Merged = { source: string; target: string; messages: Map<string, string>; labels: string[] };
+  const merged = new Map<string, Merged>();
+  const addMessage = (messages: Map<string, string>, node: Node) => {
+    if (isMessage(node)) messages.set(messageName(node), MESSAGE_COLLECTIONS[node.type!]);
+  };
+
+  edges.forEach((edge) => {
+    const from = representatives.get(edge.source);
+    if (from?.kind !== 'node') return;
+    // Follow the edge through carried nodes to the node(s) it reaches, collecting the messages on the way
+    const stack = [{ id: edge.target, messages: new Map<string, string>(), labels: [String(edge.label ?? '')] }];
+    const visited = new Set<string>();
+    addMessage(stack[0].messages, byId.get(edge.source)!);
+    while (stack.length) {
+      const current = stack.pop()!;
+      if (visited.has(current.id)) continue;
+      visited.add(current.id);
+      const node = byId.get(current.id);
+      const to = representatives.get(current.id);
+      if (!node || !to || to.kind === 'drop') continue;
+      const messages = new Map(current.messages);
+      addMessage(messages, node);
+      if (to.kind === 'carrier') {
+        (outgoing.get(current.id) ?? []).forEach((next) => stack.push({ id: next.target, messages, labels: [] as string[] }));
+        continue;
+      }
+      // Edges inside what was collapsed disappear, and so do edges to what a node is in (e.g. a system and the
+      // messages left loose in its domain, which fold into the domain)
+      if (from.id === to.id || isInside(from.id, to.id) || isInside(to.id, from.id)) continue;
+      const key = `${from.id}->${to.id}`;
+      const entry: Merged = merged.get(key) ?? { source: from.id, target: to.id, messages: new Map(), labels: [] };
+      messages.forEach((collection, name) => entry.messages.set(name, collection));
+      entry.labels.push(...current.labels.filter(Boolean));
+      merged.set(key, entry);
+    }
+  });
+
+  const keptIds = new Set([...representatives.values()].flatMap((rep) => (rep.kind === 'node' ? [rep.id] : [])));
+  return {
+    nodes: nodes.filter((node) => keptIds.has(node.id)),
+    edges: [...merged.values()].map(({ source, target, messages, labels }): Edge => {
+      const collections = new Set(messages.values());
+      const collection = collections.size === 1 ? [...collections][0] : undefined;
+      return {
+        id: `level-${source}-${target}`,
+        source,
+        target,
+        type: collection ? 'animated' : 'smoothstep',
+        label: getMessagesLabel(messages) ?? [...new Set(labels)].join(', '),
+        markerEnd: EDGE_MARKER,
+        data: collection ? { message: { collection } } : {},
+      };
+    }),
+  };
+};
+
+/**
+ * The system and domain each node is in: the containers it sits inside, or the domain and system cards
+ * connected to it with "contains"
+ */
+const getContainers = (nodes: Node[], edges: Edge[]) => {
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const containers = new Map<string, { system?: string; domain?: string }>();
+  const add = (nodeId: string, container: Node) => {
+    const entry = containers.get(nodeId) ?? {};
+    if (isSystem(container)) entry.system ??= container.id;
+    else entry.domain ??= container.id;
+    containers.set(nodeId, entry);
+  };
+  for (const node of nodes) {
+    for (
+      let parent = node.parentId ? byId.get(node.parentId) : undefined;
+      parent;
+      parent = parent.parentId ? byId.get(parent.parentId) : undefined
+    ) {
+      if (isContainer(parent)) add(node.id, parent);
+    }
+  }
+  for (const edge of edges) {
+    const container = byId.get(edge.source);
+    if (container && isContainer(container) && edge.label === 'contains') add(edge.target, container);
+  }
+  return containers;
+};
+
+/**
+ * Containers left with nothing inside them at a level become compact boxes (same id, so switching levels
+ * grows and shrinks them); containers with something inside are sized to fit by the layout
+ */
+const compactEmptyGroups = ({ nodes, edges }: { nodes: Node[]; edges: Edge[] }) => {
+  const parents = new Set(nodes.map((node) => node.parentId).filter(Boolean));
+  return {
+    edges,
+    nodes: nodes.map((node) => {
+      if (!isGroupType(node.type)) return node;
+      if (parents.has(node.id)) return { ...node, width: undefined, height: undefined, measured: undefined };
+      return { ...node, ...COLLAPSED_GROUP_SIZE, measured: undefined };
+    }),
+  };
+};
+
+/** L2: messages and channels hidden, the nodes either side connected directly */
+const level2 = (nodes: Node[], edges: Edge[]) =>
+  collapseGraph(nodes, edges, (node) => (isCarrier(node) ? { kind: 'carrier' } : { kind: 'node', id: node.id }));
+
+/**
+ * L1 as EventCatalog's diagrams draw it: systems as cards (with how many services they hold), connected by plain
+ * edges labelled with the messages between them
+ */
+const asSystemsLevel = (
+  { nodes, edges }: { nodes: Node[]; edges: Edge[] },
+  { all, containers }: { all: Node[]; containers: ReturnType<typeof getContainers> }
+) => {
+  const servicesIn = new Map<string, number>();
+  for (const node of all) {
+    const system = node.type === 'service' ? containers.get(node.id)?.system : undefined;
+    if (system) servicesIn.set(system, (servicesIn.get(system) ?? 0) + 1);
+  }
+  return {
+    nodes: nodes.map((node): Node => {
+      if (node.type !== GROUP_TYPES.system) return node;
+      const { id, parentId, position, data } = node;
+      return {
+        id,
+        type: 'system',
+        position,
+        ...(parentId && { parentId }),
+        data: { mode: 'full', ...data, servicesCount: servicesIn.get(id) ?? 0 },
+      };
+    }),
+    edges: edges.map(({ type: _, data: __, ...edge }): Edge => ({ ...edge, type: 'default' })),
+  };
+};
+
+/** L1: services folded into their system (or domain); actors, external systems and loose services stay */
+const level1 = (nodes: Node[], edges: Edge[]) => {
+  const containers = getContainers(nodes, edges);
+  const collapsed = collapseGraph(nodes, edges, (node) => {
+    const container = containers.get(node.id);
+    // Systems stay (inside their domain's container, if they're in one); everything else folds into its system or domain
+    if (isContainer(node) && (isSystem(node) || !container?.system)) return { kind: 'node', id: node.id };
+    if (container?.system) return { kind: 'node', id: container.system };
+    // Messages and channels connect the systems either side, even when they sit in a domain rather than a system
+    if (isCarrier(node)) return { kind: 'carrier' };
+    if (container?.domain) return { kind: 'node', id: container.domain };
+    if (node.type === 'data' || node.type === 'note') return { kind: 'drop' };
+    return { kind: 'node', id: node.id };
+  });
+  return asSystemsLevel(collapsed, { all: nodes, containers });
+};
+
+/** The graph for a level (not laid out: positions come from the layout) */
+export const getLevelGraph = (nodes: Node[], edges: Edge[], level: Level) => {
+  if (level === 1) return compactEmptyGroups(level1(nodes, edges));
+  if (level === 2) return compactEmptyGroups(level2(nodes, edges));
+  return { nodes, edges };
+};
+
+/** Why a level can't be shown for this canvas, if it can't */
+export const getLevelUnavailableReason = (nodes: Node[], level: Level): string | undefined => {
+  if (level === 1 && !nodes.some(isContainer))
+    return 'Not available: add a domain or system from the catalog to see how they relate';
+  if (level === 2 && !nodes.some(isCarrier)) return 'Not available: there are no messages or channels to hide';
+  return undefined;
+};