@eventcatalog/core 5.0.0-beta.11 → 5.0.0-beta.12

package/eventcatalog/src/features/studio/components/canvas-nodes.tsx

@@ -1,8 +1,8 @@
-import { createContext, memo, useCallback, useContext, useRef, useState } from 'react';
+import { createContext, memo, useCallback, useContext, useMemo, useRef, useState } from 'react';
 import { NodeResizeControl, NodeResizer, ResizeControlVariant, useStoreApi, type NodeProps, type NodeTypes } from '@xyflow/react';
-import { DomainCardNode, nodeComponents, SystemGroupNode } from '@eventcatalog/visualiser';
+import { diagramNodeComponents, DomainCardNode, memoNode, SystemGroupNode } from '@eventcatalog/visualiser';
 import { GROUP_PADDING } from '../grouping';
-import { getNodeName, GROUP_TYPES, nodeDefinitions } from '../node-types';
+import { getNodeName, GROUP_TYPES } from '../node-types';
 
 /** How the canvas draws each kind of node: the visualiser's nodes, notes and text written on the canvas, and resizable containers */
 
@@ -14,9 +14,6 @@ export const UpdateNodeDataContext = createContext<UpdateNodeData>(() => {});
 // Which container something dragged would drop into, to highlight it
 export const DropTargetContext = createContext<string | null>(null);
 
-// The visualiser types its node components' props as nodes (Node<Data>) rather than React Flow's NodeProps, so
-// they don't type-check as NodeTypes, though that's what React Flow renders them with
-const visualiserNodes = nodeComponents as unknown as NodeTypes;
 const SystemGroupComponent: NodeTypes[string] = SystemGroupNode;
 
 /** The handles that set a node's width, on either side (its height follows what's written in it) */
@@ -167,6 +164,18 @@ const TextNode = memo(function TextNode({ id, data, selected }: NodeProps) {
   );
 });
 
+/** A domain inside another one is a subdomain (badged as one, like the visualiser), unless its data says otherwise */
+const useDomainData = ({ type, data, parentId }: Pick<NodeProps, 'type' | 'data' | 'parentId'>) =>
+  useMemo(() => {
+    const isDomain = type === GROUP_TYPES.domain || type === 'context-domain';
+    return isDomain && parentId && data.subdomain === undefined ? { ...data, subdomain: true } : data;
+  }, [type, data, parentId]);
+
+/** A domain card, badged as a subdomain when it's in another domain */
+const DomainCard = memo(function DomainCard(props: NodeProps) {
+  return <DomainCardNode {...props} data={useDomainData(props)} />;
+});
+
 /**
  * A domain or system as a container: resizable when selected, highlighted when something's dragged over it.
  * Like frames in design tools, it's moved and selected by its header, and dragging inside it draws a selection
@@ -174,6 +183,7 @@ const TextNode = memo(function TextNode({ id, data, selected }: NodeProps) {
  */
 const GroupNode = memo(function GroupNode(props: NodeProps) {
   const isDropTarget = useContext(DropTargetContext) === props.id;
+  const data = useDomainData(props);
   const store = useStoreApi();
   // Where what's inside has to stay (with room around it and for the header), in the container's parent's
   // coordinates: found when a resize starts, so it can't be resized smaller than what's in it
@@ -224,7 +234,7 @@ const GroupNode = memo(function GroupNode(props: NodeProps) {
         lineClassName="!border-[rgb(var(--ec-accent))]"
         handleClassName="!h-2.5 !w-2.5 !rounded-sm !border-2 !bg-[rgb(var(--ec-card-bg))] !border-[rgb(var(--ec-accent))]"
       />
-      <SystemGroupComponent {...props} />
+      <SystemGroupComponent {...props} data={data} />
       {/* The header (and the badge on its border) */}
       <div className="ec-group-grip absolute inset-x-0 -top-3 h-[60px] cursor-grab" />
       {isDropTarget ? (
@@ -239,17 +249,23 @@ const GroupNode = memo(function GroupNode(props: NodeProps) {
   );
 });
 
-export const nodeTypes: NodeTypes = {
-  ...Object.fromEntries(
-    nodeDefinitions.map((definition) => [
-      definition.type,
-      definition.type === 'note' ? StickyNote : definition.type === 'text' ? TextNode : visualiserNodes[definition.type],
-    ])
-  ),
-  // Only dropped in from the catalog
-  system: visualiserNodes.system,
-  'context-domain': DomainCardNode,
+const components: NodeTypes = {
+  // Everything the visualiser draws, drawn the same (so a diagram's levels look as they do there). It types its
+  // components' props as nodes (Node<Data>) rather than React Flow's NodeProps, which they're rendered with.
+  ...(diagramNodeComponents as unknown as NodeTypes),
+  // Written on the canvas
+  note: StickyNote,
+  text: TextNode,
+  // Actors look like the visualiser's actors on its architecture diagrams
+  actor: diagramNodeComponents['context-actor'] as NodeTypes[string],
+  'context-domain': DomainCard,
   // Domains and systems as containers
   [GROUP_TYPES.domain]: GroupNode,
   [GROUP_TYPES.system]: GroupNode,
 };
+
+// React Flow gives every node its position, which changes on every frame it moves (dragged, in a dragged container,
+// or gliding to a layout): like the visualiser's, nodes render again only when something else changes
+export const nodeTypes: NodeTypes = Object.fromEntries(
+  Object.entries(components).map(([type, component]) => [type, memoNode(component)])
+);

package/eventcatalog/src/features/studio/flow-state.ts

@@ -52,6 +52,35 @@ export const patchShared = <T extends { id: string }>(
   return [...(removed.size ? patched.filter((item) => !removed.has(item.id)) : patched), ...added];
 };
 
+/** Whether two plain values (what nodes and edges hold) are the same, comparing what's in them */
+const isSame = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true;
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) !== Array.isArray(b)) return false;
+  const keys = Object.keys(a);
+  return (
+    keys.length === Object.keys(b).length &&
+    keys.every((key) => isSame((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key]))
+  );
+};
+
+/**
+ * Items worked out again (e.g. a level arranged again), keeping each one that hasn't changed as the object already
+ * shown (so React Flow doesn't re-render it), and the local-only state of the ones that have. Returns `previous`
+ * itself when nothing changed.
+ */
+export const keepUnchanged = <T extends { id: string }>(previous: T[], next: T[], localKeys: readonly (keyof T)[]): T[] => {
+  const shown = new Map(previous.map((item) => [item.id, item]));
+  const local = new Set<PropertyKey>(localKeys);
+  const kept = next.map((item) => {
+    const before = shown.get(item.id);
+    if (!before) return item;
+    const keys = new Set([...Object.keys(before), ...Object.keys(item)]) as Set<keyof T>;
+    const same = [...keys].every((key) => local.has(key) || isSame(before[key], item[key]));
+    return same ? before : withLocalState(item, before, localKeys);
+  });
+  return kept.length === previous.length && kept.every((item, index) => item === previous[index]) ? previous : kept;
+};
+
 /** Where nodes being dragged are, by id, until they're dropped (and saved) */
 export type Moves = ReadonlyMap<string, XYPosition>;
 

package/eventcatalog/src/features/studio/from-visualiser.ts

@@ -0,0 +1,138 @@
+import type { Edge, Node } from '@xyflow/react';
+import type { VisualiserSnapshot } from '@eventcatalog/visualiser';
+import { getNodeCatalogResource } from '@utils/node-graphs/node-resource';
+import type { DiagramLevelsSpec, NewCanvasEdges, NodeSpecs } from './canvas-actions';
+import { DEFAULT_NODE_SIZE, isCatalogCollection, isGroupType } from './node-types';
+
+/**
+ * A canvas started from a diagram (the visualiser's "Open in Studio"): the catalog resources and actors it shows,
+ * where they are on it (the same top-left corners), in the domains and systems they're shown in, and the
+ * connections between them, drawn along the same routes. Other nodes (e.g. flow steps, users, entities) are left
+ * out, with their connections. Its levels 1 and 2 come as the diagram shows them, for Studio to show them the same.
+ */
+
+// Actors (people and roles) aren't catalog resources: they go on the canvas as Studio's actors, by the name shown
+const ACTOR_TYPES = new Set(['context-actor', 'actor']);
+const actorNameOf = (node: VisualiserSnapshot['nodes'][number]) =>
+  node.type && ACTOR_TYPES.has(node.type) && typeof node.data.name === 'string' ? node.data.name : undefined;
+
+export const canvasFromVisualiser = (
+  snapshot: VisualiserSnapshot
+): { nodes: NodeSpecs; edges: NewCanvasEdges; levels: DiagramLevelsSpec } => {
+  const byId = new Map(snapshot.nodes.map((node) => [node.id, node]));
+  const depthOf = (node: VisualiserSnapshot['nodes'][number]): number => {
+    const parent = node.parentId ? byId.get(node.parentId) : undefined;
+    return parent ? 1 + depthOf(parent) : 0;
+  };
+
+  const containers = new Set<string>();
+  const parentOf = new Map<string, string>();
+  const nodes = [...snapshot.nodes]
+    // Containers before what's in them (specs refer to containers given before them)
+    .sort((a, b) => depthOf(a) - depthOf(b))
+    .flatMap((node) => {
+      const resource = getNodeCatalogResource(node);
+      const fromCatalog =
+        resource && isCatalogCollection(resource.collection) ? { collection: resource.collection, id: resource.id } : undefined;
+      const actorName = actorNameOf(node);
+      if (!fromCatalog && !actorName) return [];
+      // Domains and systems shown as boxes are containers on the canvas
+      const container = isGroupType(node.type);
+      // In the innermost container shown that's on the canvas
+      let inside: string | undefined;
+      for (let parent = node.parentId; parent && !inside; parent = byId.get(parent)?.parentId) {
+        if (containers.has(parent)) inside = parent;
+      }
+      if (container) containers.add(node.id);
+      if (inside) parentOf.set(node.id, inside);
+      // Where it is: its top-left corner, as cards are put by their centre at the size they're created at (and
+      // render at the size they need from there), and containers at their size
+      const left = node.center.x - node.width / 2;
+      const top = node.center.y - node.height / 2;
+      return [
+        {
+          ref: node.id,
+          ...(fromCatalog ? { resource: fromCatalog } : { type: 'actor', name: actorName }),
+          ...(container
+            ? { x: node.center.x, y: node.center.y, container: true, width: node.width, height: node.height }
+            : { x: left + DEFAULT_NODE_SIZE.width / 2, y: top + DEFAULT_NODE_SIZE.height / 2 }),
+          ...(inside && { inside }),
+        },
+      ];
+    });
+
+  // Connections between nodes on the canvas, not between a container and what's in it (it holds it instead)
+  const onCanvas = new Set(nodes.map((node) => node.ref));
+  const isInside = (nodeId: string, containerId: string) => {
+    for (let parent = parentOf.get(nodeId); parent; parent = parentOf.get(parent)) if (parent === containerId) return true;
+    return false;
+  };
+  const edges = snapshot.edges
+    .filter(({ source, target }) => onCanvas.has(source) && onCanvas.has(target) && source !== target)
+    .filter(({ source, target }) => !isInside(source, target) && !isInside(target, source))
+    .map(({ source, target, label, route }) => ({ from: source, to: target, ...(label && { label }), ...(route && { route }) }));
+
+  const levels = {
+    ...(snapshot.levels[1] && { 1: levelFromVisualiser(snapshot.levels[1], nodes) }),
+    ...(snapshot.levels[2] && { 2: levelFromVisualiser(snapshot.levels[2], nodes) }),
+    ...(Object.keys(snapshot.unavailableLevels).length > 0 && { unavailable: snapshot.unavailableLevels }),
+  };
+  return { nodes, edges, levels };
+};
+
+const sameResource = (a?: { collection: string; id: string }, b?: { collection: string; id: string }) =>
+  !!a && !!b && a.collection === b.collection && a.id === b.id;
+const sizeOf = (node: Node) => ({
+  width: typeof node.style?.width === 'number' ? node.style.width : (node.width ?? node.measured?.width),
+  height: typeof node.style?.height === 'number' ? node.style.height : (node.height ?? node.measured?.height),
+});
+
+/**
+ * One of the diagram's levels, as it shows it: each node stands for the canvas node with the same id (on level 3),
+ * or the same catalog resource (e.g. a system shown as a card on level 1 and as a container on level 3), so moving
+ * between levels glides from one to the other. Nodes only on the level keep their own id.
+ */
+const levelFromVisualiser = (level: { nodes: Node[]; edges: Edge[] }, specs: NodeSpecs) => {
+  const used = new Set<string>();
+  const refs = new Map<string, string>();
+  for (const node of level.nodes) {
+    const resource = getNodeCatalogResource(node);
+    const ref = [
+      specs.find((spec) => spec.ref === node.id)?.ref,
+      specs.find((spec) => sameResource(spec.resource, resource))?.ref,
+    ].find((candidate) => candidate && !used.has(candidate));
+    refs.set(node.id, ref ?? node.id);
+    used.add(ref ?? node.id);
+  }
+  return {
+    nodes: level.nodes.map((node) => {
+      const { width, height } = sizeOf(node);
+      // The diagram marks the resource whose page it's on ("Viewing"): a canvas isn't on one
+      const { isFocused: _, ...data } = node.data as Record<string, unknown>;
+      return {
+        ref: refs.get(node.id)!,
+        type: node.type ?? 'default',
+        data,
+        ...(node.parentId && refs.has(node.parentId) && { parent: refs.get(node.parentId) }),
+        x: node.position.x,
+        y: node.position.y,
+        ...(isGroupType(node.type) && width && height && { width, height }),
+      };
+    }),
+    edges: level.edges.flatMap((edge) => {
+      const [from, to] = [refs.get(edge.source), refs.get(edge.target)];
+      if (!from || !to) return [];
+      return [
+        {
+          from,
+          to,
+          ...(typeof edge.label === 'string' && { label: edge.label }),
+          ...(edge.type && { type: edge.type }),
+          ...(edge.style && { style: edge.style as Record<string, unknown> }),
+          ...(edge.markerEnd && { markerEnd: edge.markerEnd }),
+          ...(edge.data && { data: edge.data }),
+        },
+      ];
+    }),
+  };
+};

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

@@ -78,6 +78,10 @@ export const findGroupAtPoint = (point: XYPosition, nodes: Node[]): Node | undef
     .sort((a, b) => getDepth(b, lookup) - getDepth(a, lookup))[0];
 };
 
+/** The container something added goes in: the one asked for (by id), else the one it's dropped on */
+export const containerFor = (point: XYPosition, nodes: Node[], inside?: string): Node | undefined =>
+  inside ? nodes.find((node) => node.id === inside && isGroupType(node.type)) : findGroupAtPoint(point, nodes);
+
 /** A node moved into (or out of, without a parentId) a container, staying in the same place on the canvas */
 export const withParent = (node: Node, parentId: string | undefined, nodes: Node[]): Node => {
   const lookup = byId(nodes);

package/eventcatalog/src/features/studio/hooks/use-canvas-webmcp.ts

@@ -3,9 +3,9 @@ import { z } from 'zod';
 import type * as Y from 'yjs';
 import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';
 import { replyToThread, setThreadResolved, type Author, CANVAS_STATUSES, setCanvasStatus } from '../canvas-doc';
+import { CATALOG_COLLECTIONS } from '../node-types';
 import {
   ADD_TO_CANVAS_DESCRIPTION,
-  CATALOG_COLLECTIONS,
   describeCanvas,
   edgeSpecsSchema,
   nodeSpecsSchema,

package/eventcatalog/src/features/studio/hooks/use-counter-scale.ts

@@ -0,0 +1,20 @@
+import { useLayoutEffect, type RefObject } from 'react';
+import { useStoreApi } from '@xyflow/react';
+
+/** 1 / zoom, for things drawn in the canvas's coordinates that stay the same size on screen (`scale(var(...))`) */
+export const COUNTER_SCALE = '--studio-counter-scale';
+
+/**
+ * Keeps COUNTER_SCALE on an element as the canvas zooms, outside React: what's counter-scaled with it (e.g. comment
+ * pins) stays the same size on screen without re-rendering on every frame of a zoom
+ */
+export function useCounterScale(ref: RefObject<HTMLElement | null>) {
+  const store = useStoreApi();
+  useLayoutEffect(() => {
+    const apply = (zoom: number) => ref.current?.style.setProperty(COUNTER_SCALE, String(1 / zoom));
+    apply(store.getState().transform[2]);
+    return store.subscribe((state, previous) => {
+      if (state.transform[2] !== previous.transform[2]) apply(state.transform[2]);
+    });
+  }, [store, ref]);
+}

package/eventcatalog/src/features/studio/hooks/use-follow-camera.ts

@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useRef } from 'react';
 import { getViewportForBounds, useReactFlow, useStore, type Rect } from '@xyflow/react';
+import { DIAGRAM_FIT_VIEW_OPTIONS } from '@eventcatalog/visualiser';
 import type { Peer } from './presence-store';
 
 /**
@@ -30,10 +31,13 @@ const inView = (rect: Rect, view: Rect, margin: number) =>
 
 export function useFollowCamera({
   enabled,
+  fitsContent,
   agentsWorking,
   getAgents,
 }: {
   enabled: boolean;
+  /** Whether it fits the canvas's content when it arrives (the canvas people edit, not a level, fitted on its own) */
+  fitsContent: boolean;
   /** Whether any agent is working on the canvas (has a pointer on it) */
   agentsWorking: boolean;
   /** The agents working, with where their pointers are now (read when the camera checks, not on every move) */
@@ -61,11 +65,12 @@ export function useFollowCamera({
       hasFitContent.current = false;
       return;
     }
-    if (hasFitContent.current || !width) return;
+    if (hasFitContent.current || !width || !fitsContent) return;
     hasFitContent.current = true;
-    const frame = requestAnimationFrame(() => void fitView({ padding: PADDING, maxZoom: MAX_ZOOM, duration: 300 }));
+    // Fitted like the visualiser fits a diagram
+    const frame = requestAnimationFrame(() => void fitView({ ...DIAGRAM_FIT_VIEW_OPTIONS, duration: 300 }));
     return () => cancelAnimationFrame(frame);
-  }, [hasNodes, width]);
+  }, [hasNodes, width, fitsContent]);
 
   const follow = useCallback(() => {
     const { enabled, getAgents } = latest.current;

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

@@ -25,7 +25,9 @@ import {
   fitGroupToChildren,
   getCanvasMaps,
   moveNode,
+  placeNode,
   changesNodesOrEdges,
+  getStructureKey,
   getCanvasStatus,
   readMeta,
   reopenIfDecided,
@@ -34,6 +36,10 @@ import {
   setMeta,
   type Author,
   type CanvasStatus,
+  type DiagramLevels,
+  type LevelPlace,
+  readLevelLayout,
+  setLevelPlaces,
   type StatusChange,
   setNodeParent,
   type RenderedSizes,
@@ -41,7 +47,7 @@ import {
 } from '../canvas-doc';
 import { applyLayout } from '../agent-choreography';
 import { keepDragged, LOCAL_EDGE_KEYS, LOCAL_NODE_KEYS, patchShared, withPositions } from '../flow-state';
-import { findGroupAtPoint, toRelativePosition, type NodePreview } from '../grouping';
+import { containerFor, toRelativePosition, type NodePreview } from '../grouping';
 import type { LayoutResult } from '../layout';
 import { canGoInContainer, getNodeDefinition, isGroupType } from '../node-types';
 import { startToolSync, type ToolSync } from '../tool-sync';
@@ -67,6 +73,10 @@ const LOCAL_ORIGIN = Symbol('studio-local');
 export const BROWSER_AGENT_ORIGIN = Symbol('studio-browser-agent');
 /** Status changes: synced, but not undone (undo takes back edits, not decisions about the canvas) */
 const STATUS_ORIGIN = Symbol('studio-status');
+/** Where L1 and L2 put what's new on them, kept so it stays there: synced, not undone (nobody did it) */
+const LEVEL_PLACEMENT_ORIGIN = Symbol('studio-level-placement');
+
+const NO_LEVEL_LAYOUTS = { 1: new Map(), 2: new Map() } as const;
 
 export type Status = 'connecting' | 'connected' | 'disconnected';
 export type Transport = 'websocket' | 'tools';
@@ -121,6 +131,13 @@ export function useStudioFlow({
   const [doc, setDoc] = useState<Y.Doc | null>(null);
   const [history, setHistory] = useState({ canUndo: false, canRedo: false });
   const [title, setTitle] = useState<string | undefined>();
+  // L1 and L2 of the diagram the canvas was opened from, if it was
+  const [diagramLevels, setDiagramLevels] = useState<DiagramLevels | undefined>();
+  // What's on the canvas and how it's connected (getStructureKey): worked out when the document's nodes or edges
+  // change, which drags don't do (they're in presence until the drop)
+  const [structureKey, setStructureKey] = useState('');
+  // Where things are on L1 and L2, as people arranged them
+  const [levelLayouts, setLevelLayouts] = useState<Record<1 | 2, ReadonlyMap<string, LevelPlace>>>(NO_LEVEL_LAYOUTS);
   const [canvasStatus, setCanvasStatusState] = useState<{ status: CanvasStatus; history: StatusChange[] }>(NEW_CANVAS_STATUS);
   const [transport, setTransport] = useState<Transport>('websocket');
   // Someone deleted the canvas: the server closed it for everyone, and won't open it again
@@ -139,16 +156,29 @@ export function useStudioFlow({
     setEdges([]);
 
     const doc = new Y.Doc();
-    const { nodes: yNodes, edges: yEdges, threads: yThreads, meta: yMeta } = getCanvasMaps(doc);
+    const { nodes: yNodes, edges: yEdges, threads: yThreads, meta: yMeta, levelLayouts: yLevelLayouts } = getCanvasMaps(doc);
+    const syncLevelLayouts = (event: Y.YMapEvent<LevelPlace>) => {
+      const changed = new Set([...event.keysChanged].map((key) => Number(key.split(':')[0]) as 1 | 2));
+      setLevelLayouts((current) => {
+        const next = { ...current };
+        changed.forEach((level) => (next[level] = readLevelLayout(doc, level)));
+        return next;
+      });
+    };
+    yLevelLayouts.observe(syncLevelLayouts);
+    setLevelLayouts(NO_LEVEL_LAYOUTS);
     const syncMeta = (event: Y.YMapEvent<unknown>) => {
       const meta = readMeta(doc);
       setTitle(meta.title);
+      if (event.keysChanged.has('diagramLevels')) setDiagramLevels(meta.diagramLevels);
       if (event.keysChanged.has('status') || event.keysChanged.has('statusHistory'))
         setCanvasStatusState({ status: getCanvasStatus(meta), history: meta.statusHistory ?? [] });
       if (event.keysChanged.has('layoutAt')) onLayoutRef.current?.();
     };
     yMeta.observe(syncMeta);
     setTitle(undefined);
+    setStructureKey('');
+    setDiagramLevels(undefined);
     setCanvasStatusState(NEW_CANVAS_STATUS);
     // Changing an accepted (or rejected) canvas here makes it a draft again, for everyone. Changes from others arrive
     // already reopened by whoever made them.
@@ -169,6 +199,12 @@ export function useStudioFlow({
       );
     };
     doc.on('afterTransaction', reopenOnEdit);
+    const syncStructure = (transaction: Y.Transaction) => {
+      // Drops and resizes here only move and size things (putting something in a container isn't LOCAL_ORIGIN)
+      if (transaction.origin !== LOCAL_ORIGIN && changesNodesOrEdges(transaction))
+        setStructureKey(getStructureKey(Array.from(yNodes.values()), Array.from(yEdges.values())));
+    };
+    doc.on('afterTransaction', syncStructure);
     // One presence for whichever connection is used
     const awareness = new Awareness(doc);
     awareness.setLocalStateField('user', user.current);
@@ -249,7 +285,7 @@ export function useStudioFlow({
     // A socket that isn't let in within a few seconds (blocked, or never answered) is given up for tool calls
     if (syncViaTools) fallback = setTimeout(() => !socketConnected && syncThroughTools(), SOCKET_TIMEOUT_MS);
     // 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], {
+    const undoManager = new Y.UndoManager([yNodes, yEdges, yThreads, yLevelLayouts], {
       captureTimeout: 500,
       trackedOrigins: new Set([null, LOCAL_ORIGIN]),
     });
@@ -329,9 +365,11 @@ export function useStudioFlow({
       sender.destroy();
       stopToolSync?.();
       yNodes.unobserve(syncNodes);
+      yLevelLayouts.unobserve(syncLevelLayouts);
       yEdges.unobserve(syncEdges);
       yMeta.unobserve(syncMeta);
       doc.off('afterTransaction', reopenOnEdit);
+      doc.off('afterTransaction', syncStructure);
       presenceStore.destroy();
       undoManager.destroy();
       provider.destroy();
@@ -384,10 +422,10 @@ export function useStudioFlow({
     dragged.current.forEach((position, id) => moveNode(doc, id, position));
     // Containers as they grew around what was dragged, and what else is in them (moved the other way if they grew up
     // or left). Dragged nodes are where React Flow dropped them, already in their containers' grown coordinates.
-    dragPreview.current.forEach(({ position, width, height }, id) => {
-      const node = getCanvasMaps(doc).nodes.get(id);
-      if (node) getCanvasMaps(doc).nodes.set(id, { ...node, position, ...(width !== undefined && { width, height }) });
-    });
+    // Only what actually moved or grew is written (the preview has everything in those containers)
+    dragPreview.current.forEach(({ position, width, height }, id) =>
+      placeNode(doc, id, position, width !== undefined && height !== undefined ? { width, height } : undefined)
+    );
     dragPreview.current = new Map();
     dragged.current.clear();
     const shared = sharedRef.current;
@@ -474,12 +512,18 @@ export function useStudioFlow({
    * 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[]) => {
+    (
+      type: string,
+      data: Record<string, unknown>,
+      center: XYPosition,
+      connect?: (id: string, existing: Node[]) => Edge[],
+      inside?: string
+    ) => {
       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 = canGoInContainer(type) ? findGroupAtPoint(center, existing) : undefined;
+        // In the container asked for, else the one it's dropped on
+        const group = canGoInContainer(type) ? containerFor(center, existing, inside) : undefined;
         const node = group
           ? { ...built, parentId: group.id, position: toRelativePosition(built.position, group.id, existing) }
           : built;
@@ -491,11 +535,11 @@ export function useStudioFlow({
     []
   );
 
-  /** Add a node of a registry type, centred on a canvas position */
+  /** Add a node of a registry type, centred on a canvas position (in a container, if asked) */
   const addNode = useCallback(
-    (type: string, center: XYPosition) => {
+    (type: string, center: XYPosition, inside?: string) => {
       const definition = getNodeDefinition(type);
-      return definition ? insertNode(type, definition.createData(), center) : undefined;
+      return definition ? insertNode(type, definition.createData(), center, undefined, inside) : undefined;
     },
     [insertNode]
   );
@@ -510,6 +554,12 @@ export function useStudioFlow({
 
   /** 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)), []);
+  /** Puts things where they go on L1 or L2: moved there by someone (undone like any edit), or placed by the level */
+  const setLevelLayout = useCallback(
+    (level: 1 | 2, places: ReadonlyMap<string, LevelPlace>, by: 'person' | 'level' = 'person') =>
+      withDoc((doc) => setLevelPlaces(doc, level, places), by === 'level' ? LEVEL_PLACEMENT_ORIGIN : null),
+    []
+  );
 
   /** Adds ready-made nodes and edges (e.g. a container with what's in it) in one change */
   const insertNodes = useCallback(
@@ -572,9 +622,13 @@ export function useStudioFlow({
     updateNodeData,
     deleteNodes,
     applyPositions,
+    levelLayouts,
+    setLevelLayout,
     insertNodes,
     setParent,
     title,
+    diagramLevels,
+    structureKey,
     rename,
     canvasStatus,
     changeStatus,

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

@@ -1,5 +1,6 @@
 import type { Edge, Node, XYPosition } from '@xyflow/react';
 import { layoutWithElk } from '@eventcatalog/visualiser/layout';
+import { getEdgeRoute, type EdgeRoute } from './canvas-doc';
 import { isGroupType, isOnLevel } from './node-types';
 
 /**
@@ -17,26 +18,39 @@ export const withGroupSizes = (nodes: Node[]) =>
     return { ...node, width, height, style };
   });
 
-export type LayoutResult = Map<string, { position: XYPosition; size?: { width: number; height: number } }>;
+export type LayoutResult = {
+  /** Where each node goes (relative to its container, if it's in one), and containers' new sizes */
+  nodes: Map<string, { position: XYPosition; size?: { width: number; height: number } }>;
+  /** How each connection is drawn (around the nodes), by edge id */
+  routes: Map<string, EdgeRoute>;
+};
 
 /**
- * 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. Notes added on L1 or L2 aren't on this canvas, so they stay where they are.
+ * The canvas laid out: new positions for its nodes, new sizes for containers, and routes for the connections
+ * (drawn like the visualiser's: around the nodes, following them when they're moved, and as a plain step once
+ * they've moved too far for it). Notes added on L1 or L2 aren't on this canvas, so they stay where they are.
  */
 export const getLayoutPositions = async (nodes: Node[], edges: Edge[]): Promise<LayoutResult> => {
   const onCanvas = nodes.filter((node) => isOnLevel(node, 3));
-  if (onCanvas.length === 0) return new Map();
+  if (onCanvas.length === 0) return { nodes: new Map(), routes: new Map() };
   const ids = new Set(onCanvas.map((node) => node.id));
   const between = edges.filter((edge) => ids.has(edge.source) && ids.has(edge.target));
-  const laidOut = withGroupSizes((await layoutGraph(onCanvas, between)).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 } }),
-      },
-    ])
-  );
+  const laidOut = await layoutGraph(onCanvas, between);
+  return {
+    nodes: new Map(
+      withGroupSizes(laidOut.nodes).map((node) => [
+        node.id,
+        {
+          position: node.position,
+          ...(isGroupType(node.type) && node.width && node.height && { size: { width: node.width, height: node.height } }),
+        },
+      ])
+    ),
+    routes: new Map(
+      laidOut.edges.flatMap((edge) => {
+        const route = getEdgeRoute(edge);
+        return route ? [[edge.id, route] as const] : [];
+      })
+    ),
+  };
 };