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

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

@@ -0,0 +1,145 @@
+import type { Edge, Node } from '@xyflow/react';
+import { getNodeSize as getLayoutSize } from '@eventcatalog/visualiser/layout';
+import type { LevelPlace } from './canvas-doc';
+import { fitGroup, getAbsolutePosition } from './grouping';
+import { getNodeSize, isGroupType } from './node-types';
+import { placeNodes } from './placement';
+
+/**
+ * L1 and L2 as people arrange them. A level's content comes from the canvas (see levels.ts), but where things are on
+ * it is its own: each level keeps a layout (a LevelPlace per node, in the canvas), so things stay where they're put.
+ * Nothing on a level moves when something's added: new things are placed next to what they connect to (like agents
+ * place what they add) and containers grow to fit.
+ */
+
+type Graph = { nodes: Node[]; edges: Edge[] };
+
+/** A container's size: as it's being worked on (width and height), or as laid out (levels size containers with style) */
+const containerSize = (node: Node) => {
+  if (node.width && node.height) return { width: node.width, height: node.height };
+  const { width, height } = node.style ?? {};
+  return typeof width === 'number' && typeof height === 'number' ? { width, height } : undefined;
+};
+
+/** The size the visualiser's layout gives a container with nothing in it (levels leave containers' size to it) */
+const emptyContainerSize = ({ type }: Pick<Node, 'type'>) => getLayoutSize({ id: '', type, position: { x: 0, y: 0 }, data: {} });
+
+/**
+ * The size something new of a type is shown at on L1 or L2: L1 shows domains and systems with nothing in them as
+ * cards, L2 as empty containers
+ */
+export const getLevelNodeSize = (type: string | undefined, level: 1 | 2) => {
+  if (!isGroupType(type)) return getNodeSize(type);
+  return level === 1 ? getNodeSize() : emptyContainerSize({ type });
+};
+
+/** Where a node is on a level, and a container's size */
+const placeOf = (node: Node): LevelPlace => ({
+  x: node.position.x,
+  y: node.position.y,
+  ...(isGroupType(node.type) && containerSize(node)),
+});
+
+/** A level's nodes where they are, by id (not its notes, which are kept on the canvas): what its layout keeps */
+export const levelPlaces = (nodes: Node[]) =>
+  new Map(nodes.filter((node) => node.type !== 'note').map((node) => [node.id, placeOf(node)]));
+
+/**
+ * A level arranged: each node where the level's layout has it, else where the diagram the canvas was opened from had
+ * it (`fallback`), and anything with neither placed next to what it connects to. Containers grow to fit what's in
+ * them. `placed` is where things the layout didn't have were put, and containers that grew (to keep, so they stay
+ * there). Undefined when nothing on the level has a place yet: it's laid out from scratch then.
+ */
+export const arrangeLevel = (
+  graph: Graph,
+  layout: ReadonlyMap<string, LevelPlace>,
+  fallback: ReadonlyMap<string, LevelPlace> = new Map()
+): { graph: Graph; placed: Map<string, LevelPlace> } | undefined => {
+  const known = (id: string) => layout.get(id) ?? fallback.get(id);
+  if (!graph.nodes.some((node) => known(node.id))) return undefined;
+
+  const placed = new Map<string, LevelPlace>();
+  // Containers carry their size as width and height while they're worked on (what placement and fitting read)
+  let nodes: Node[] = graph.nodes.map((node) => {
+    const place = known(node.id);
+    const size = isGroupType(node.type)
+      ? place?.width && place.height
+        ? { width: place.width, height: place.height }
+        : (containerSize(node) ?? emptyContainerSize(node))
+      : undefined;
+    return { ...node, position: place ? { x: place.x, y: place.y } : { x: 0, y: 0 }, ...size };
+  });
+
+  // Anything new, next to what it connects to (on the level), moving nothing that's there
+  const toPlace = nodes.filter((node) => !known(node.id)).map((node) => node.id);
+  if (toPlace.length) {
+    const positions = placeNodes(nodes, toPlace, graph.edges);
+    const lookup = new Map(nodes.map((node) => [node.id, node]));
+    nodes = nodes.map((node) => {
+      const at = positions.get(node.id);
+      if (!at) return node;
+      const parent = node.parentId ? lookup.get(node.parentId) : undefined;
+      const origin = parent ? getAbsolutePosition(parent, lookup) : { x: 0, y: 0 };
+      const moved = { ...node, position: { x: at.x - origin.x, y: at.y - origin.y } };
+      placed.set(node.id, placeOf(moved));
+      return moved;
+    });
+  }
+
+  // Containers grow to fit what's in them (the innermost first), moving nothing on the level
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  const depth = (node: Node): number => {
+    const parent = node.parentId ? byId.get(node.parentId) : undefined;
+    return parent ? 1 + depth(parent) : 0;
+  };
+  const containers = nodes.filter((node) => isGroupType(node.type)).sort((a, b) => depth(b) - depth(a));
+  for (const { id } of containers) {
+    const fit = fitGroup(id, nodes);
+    const current = nodes.find((node) => node.id === id)!;
+    const { x: dx, y: dy } = fit?.shift ?? { x: 0, y: 0 };
+    if (!fit || (!dx && !dy && fit.width === current.width && fit.height === current.height)) continue;
+    nodes = nodes.map((node) => {
+      if (node.parentId === id && (dx || dy)) {
+        const shifted = { ...node, position: { x: node.position.x + dx, y: node.position.y + dy } };
+        placed.set(node.id, placeOf(shifted));
+        return shifted;
+      }
+      if (node.id !== id) return node;
+      const grown = {
+        ...node,
+        position: { x: node.position.x - dx, y: node.position.y - dy },
+        width: fit.width,
+        height: fit.height,
+      };
+      placed.set(id, placeOf(grown));
+      return grown;
+    });
+  }
+
+  return {
+    graph: {
+      edges: graph.edges,
+      // Containers drawn at their size with style, like levels laid out from scratch
+      nodes: nodes.map(({ width, height, ...node }) =>
+        isGroupType(node.type) && width && height ? { ...node, style: { ...node.style, width, height } } : node
+      ),
+    },
+    placed,
+  };
+};
+
+/**
+ * A level's edges drawn along the routes the diagram the canvas was opened from had for the same connections (between
+ * the same two nodes), once the level's worked out from the canvas: routes follow their nodes when they move, so
+ * connections the diagram had stay drawn around what's in their way
+ */
+export const withDiagramRoutes = (edges: Edge[], diagramEdges: Edge[] = []) => {
+  const routes = new Map(
+    diagramEdges.flatMap((edge) => (edge.data?.route ? [[`${edge.source}>${edge.target}`, edge.data.route] as const] : []))
+  );
+  if (routes.size === 0) return edges;
+  return edges.map((edge) => {
+    const route = routes.get(`${edge.source}>${edge.target}`);
+    return route && !edge.data?.route ? { ...edge, data: { ...edge.data, route } } : edge;
+  });
+};

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

@@ -31,7 +31,8 @@ const isContainer = (node: Node) => CONTAINER_TYPES.has(node.type ?? '');
 const messageName = (node: Node) => String((node.data as { message?: { name?: string } }).message?.name ?? node.id);
 
 // Edges as the visualiser's levels draw them: what's folded together is joined by a plain line, and what was joined
-// through hidden messages or channels by a dashed, muted one ("bridged"), each with the visualiser's arrow
+// through hidden messages or channels by a dashed, muted one ("bridged"), each with the visualiser's arrow. On L1
+// the visualiser folds messages into the domain or system they're in, so edges to and from them are plain.
 const EDGE_STROKE = 'var(--ec-edge-stroke, #6b7280)';
 const MUTED = 'rgb(var(--ec-page-text-muted))';
 const FOLDED_EDGE = {
@@ -53,12 +54,25 @@ type Representative = { kind: 'node'; id: string } | { kind: 'carrier' } | { kin
  * (messages and channels: the nodes either side get connected directly, "bridged") or dropped. Edges between two
  * nodes that are kept as they are stay as they were (`keepDirect`, for L2); the rest are merged per pair and kind
  * (folded or bridged), labelled with the messages they carry.
+ *
+ * With `relationships` (L1), edges drawn straight between two nodes that are kept as they are (e.g. one system to
+ * another) are relationships, like the visualiser's context relationships: labelled as they were, and shown
+ * instead of the messages between the same two nodes (either way).
  */
 const collapseGraph = (
   nodes: Node[],
   edges: Edge[],
   representativeOf: (node: Node) => Representative,
-  { keepDirect = false }: { keepDirect?: boolean } = {}
+  {
+    keepDirect = false,
+    relationships = false,
+    foldsMessagesInto,
+  }: {
+    keepDirect?: boolean;
+    relationships?: boolean;
+    /** Nodes the messages they send or receive are folded into (L1: domains and systems), so edges through them are plain */
+    foldsMessagesInto?: (node: Node) => boolean;
+  } = {}
 ) => {
   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
@@ -70,7 +84,14 @@ const collapseGraph = (
   const outgoing = new Map<string, Edge[]>();
   edges.forEach((edge) => outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge]));
 
-  type Merged = { source: string; target: string; bridged: boolean; messages: Map<string, string>; labels: string[] };
+  type Merged = {
+    source: string;
+    target: string;
+    bridged: boolean;
+    relationship: boolean;
+    messages: Map<string, string>;
+    labels: string[];
+  };
   const merged = new Map<string, Merged>();
   const kept: Edge[] = [];
   const addMessage = (messages: Map<string, string>, node: Node) => {
@@ -81,7 +102,8 @@ const collapseGraph = (
     const from = representatives.get(edge.source);
     if (from?.kind !== 'node') return;
     const to = representatives.get(edge.target);
-    if (keepDirect && from.id === edge.source && to?.kind === 'node' && to.id === edge.target) return kept.push(edge);
+    const direct = from.id === edge.source && to?.kind === 'node' && to.id === edge.target;
+    if (keepDirect && direct) return kept.push(edge);
     // 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 ?? '')], bridged: false }];
     const visited = new Set<string>();
@@ -104,11 +126,13 @@ const collapseGraph = (
       // Edges inside what was collapsed disappear, and so do edges to what a node is in (e.g. a service loose in a
       // domain, folded into it, and a system in the same domain)
       if (from.id === reached.id || isInside(from.id, reached.id) || isInside(reached.id, from.id)) continue;
-      const key = `${current.bridged ? 'bridged' : 'level'}-${from.id}-${reached.id}`;
+      const relationship = relationships && direct && current.id === edge.target;
+      const key = `${relationship ? 'relationship' : current.bridged ? 'bridged' : 'level'}-${from.id}-${reached.id}`;
       const entry: Merged = merged.get(key) ?? {
         source: from.id,
         target: reached.id,
         bridged: current.bridged,
+        relationship,
         messages: new Map(),
         labels: [],
       };
@@ -119,18 +143,39 @@ const collapseGraph = (
   });
 
   const keptIds = new Set([...representatives.values()].flatMap((rep) => (rep.kind === 'node' ? [rep.id] : [])));
-  // Actors' connections are relationships, labelled as they were (like the visualiser's context relationships)
+  // A relationship between two nodes is shown instead of the messages between them (either way)
+  const related = new Set(
+    [...merged.values()]
+      .filter((entry) => entry.relationship)
+      .flatMap(({ source, target }) => [`${source}>${target}`, `${target}>${source}`])
+  );
+  // Actors' connections are relationships too, labelled as they were (even when what they use is folded)
   const isActor = (id: string) => byId.get(id)?.type === 'actor';
+  const labelOf = ({ source, target, bridged, relationship, messages, labels }: Merged) => {
+    const written = labels.length ? [...new Set(labels)].join(', ') : undefined;
+    if (relationship) return written;
+    return getMessagesLabel(messages) ?? (!bridged && (isActor(source) || isActor(target)) ? written : undefined);
+  };
   return {
     nodes: nodes.filter((node) => keptIds.has(node.id)),
     edges: [
       ...kept,
-      ...[...merged.entries()].map(([id, { source, target, bridged, messages, labels }]): Edge => {
-        const label =
-          getMessagesLabel(messages) ??
-          (!bridged && (isActor(source) || isActor(target)) && labels.length ? [...new Set(labels)].join(', ') : undefined);
-        return { id, source, target, ...(bridged ? BRIDGED_EDGE : FOLDED_EDGE), ...(label && { label }) };
-      }),
+      ...[...merged.entries()]
+        .filter(([, entry]) => entry.relationship || !related.has(`${entry.source}>${entry.target}`))
+        .map(([id, entry]): Edge => {
+          const label = labelOf(entry);
+          const folded = [entry.source, entry.target].some((nodeId) => {
+            const node = byId.get(nodeId);
+            return !!node && !!foldsMessagesInto?.(node);
+          });
+          return {
+            id,
+            source: entry.source,
+            target: entry.target,
+            ...(entry.bridged && !folded ? BRIDGED_EDGE : FOLDED_EDGE),
+            ...(label && { label }),
+          };
+        }),
     ],
   };
 };
@@ -188,8 +233,8 @@ const isWithin = (node: Node, containerId: string, byId: Map<string, Node>) => {
 };
 
 /**
- * L1 as EventCatalog's diagrams draw it: systems as cards with what's in them counted, and domains with no system in
- * them (or in their subdomains) as domain cards
+ * L1 as EventCatalog's diagrams draw it: systems as cards with what's in them counted, and domains with nothing
+ * shown in them (no system, in them or their subdomains, or subdomain) as domain cards
  */
 const asSystemsLevel = (
   { nodes, edges }: { nodes: Node[]; edges: Edge[] },
@@ -226,7 +271,12 @@ const asSystemsLevel = (
             messagesCount: messagesOf(id),
           },
         };
-      if (node.type === GROUP_TYPES.domain && !all.some((other) => isSystem(other) && isWithin(other, id, byId)))
+      // A domain container stays one while something is shown in it (a system, or a subdomain shown as a card)
+      if (
+        node.type === GROUP_TYPES.domain &&
+        !all.some((other) => isSystem(other) && isWithin(other, id, byId)) &&
+        !nodes.some((other) => isWithin(other, id, byId))
+      )
         return {
           id,
           type: 'context-domain',
@@ -248,18 +298,23 @@ const asSystemsLevel = (
 /** 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
-    // (the visualiser has them outside its domains; catalog domains on a canvas hold their messages)
-    if (isCarrier(node)) return { kind: 'carrier' };
-    if (container?.domain) return { kind: 'node', id: container.domain };
-    if (node.type === 'data' || isWrittenOnCanvas(node.type)) return { kind: 'drop' };
-    return { kind: 'node', id: node.id };
-  });
+  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
+      // (the visualiser has them outside its domains; catalog domains on a canvas hold their messages)
+      if (isCarrier(node)) return { kind: 'carrier' };
+      if (container?.domain) return { kind: 'node', id: container.domain };
+      if (node.type === 'data' || isWrittenOnCanvas(node.type)) return { kind: 'drop' };
+      return { kind: 'node', id: node.id };
+    },
+    { relationships: true, foldsMessagesInto: isContainer }
+  );
   return asSystemsLevel(collapsed, { all: nodes, allEdges: edges, containers });
 };
 

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

@@ -0,0 +1,2 @@
+/** Canvas titles are at most this long (no imports, so the browser can check it without loading a canvas) */
+export const MAX_TITLE_LENGTH = 200;

package/eventcatalog/src/features/studio/node-types.ts

@@ -12,6 +12,22 @@ export const NODE_CATEGORIES: { id: NodeCategory; label: string }[] = [
   { id: 'other', label: 'Other' },
 ];
 
+/** The catalog collections whose resources can go on a canvas */
+export const CATALOG_COLLECTIONS = [
+  'domains',
+  'systems',
+  'services',
+  'events',
+  'commands',
+  'queries',
+  'channels',
+  'containers',
+] as const;
+
+export type CatalogCollection = (typeof CATALOG_COLLECTIONS)[number];
+export const isCatalogCollection = (collection: string): collection is CatalogCollection =>
+  (CATALOG_COLLECTIONS as readonly string[]).includes(collection);
+
 /** Domains and systems as containers: boxes other nodes sit in */
 export const GROUP_TYPES = { domain: 'domain-group', system: 'system-group' } as const;
 export const isGroupType = (type?: string) => type === GROUP_TYPES.domain || type === GROUP_TYPES.system;
@@ -29,6 +45,11 @@ export type NodeDefinition = {
   defaultSize?: { width: number; height: number };
   /** Only its width is set: its height follows what's in it (text) */
   autoHeight?: boolean;
+  /**
+   * The first level of detail that shows it (it's on the more detailed ones too, see levels.ts): L1 domains, systems
+   * and actors, L2 services, data stores, text and the like, L3 messages and channels. Notes are on every level.
+   */
+  firstLevel: 1 | 2 | 3;
   createData: () => Record<string, unknown>;
 };
 
@@ -37,6 +58,7 @@ const resource = (name: string, summary: string) => ({ name, version: '0.0.1', s
 export const nodeDefinitions: NodeDefinition[] = [
   {
     type: GROUP_TYPES.domain,
+    firstLevel: 1,
     label: 'Domain',
     category: 'boundaries',
     resourceKey: 'domain',
@@ -45,6 +67,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: GROUP_TYPES.system,
+    firstLevel: 1,
     label: 'System',
     category: 'boundaries',
     resourceKey: 'system',
@@ -53,6 +76,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'service',
+    firstLevel: 2,
     category: 'architecture',
     label: 'Service',
     resourceKey: 'service',
@@ -63,6 +87,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'event',
+    firstLevel: 3,
     category: 'messages',
     label: 'Event',
     resourceKey: 'message',
@@ -70,6 +95,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'command',
+    firstLevel: 3,
     category: 'messages',
     label: 'Command',
     resourceKey: 'message',
@@ -77,6 +103,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'query',
+    firstLevel: 3,
     category: 'messages',
     label: 'Query',
     resourceKey: 'message',
@@ -84,6 +111,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'channel',
+    firstLevel: 3,
     category: 'architecture',
     label: 'Channel',
     resourceKey: 'channel',
@@ -91,6 +119,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'data',
+    firstLevel: 2,
     category: 'architecture',
     label: 'Data Store',
     resourceKey: 'data',
@@ -98,6 +127,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'view',
+    firstLevel: 2,
     category: 'architecture',
     label: 'View',
     resourceKey: 'view',
@@ -105,6 +135,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'externalSystem',
+    firstLevel: 1,
     category: 'architecture',
     unlisted: true,
     label: 'External System',
@@ -113,6 +144,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'agent',
+    firstLevel: 2,
     category: 'architecture',
     label: 'Agent',
     resourceKey: 'agent',
@@ -120,12 +152,15 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'actor',
+    firstLevel: 1,
     category: 'other',
     label: 'Actor',
-    createData: () => ({ mode: 'full', name: 'Customer', summary: 'A person using the system.' }),
+    // Drawn like the visualiser's actors (by name only); the summary is for agents and the properties panel
+    createData: () => ({ mode: 'full', name: 'Customer', summary: '' }),
   },
   {
     type: 'text',
+    firstLevel: 2,
     category: 'other',
     label: 'Text',
     defaultSize: { width: 240, height: 40 },
@@ -134,6 +169,7 @@ export const nodeDefinitions: NodeDefinition[] = [
   },
   {
     type: 'note',
+    firstLevel: 1,
     category: 'other',
     label: 'Sticky Note',
     // About square, like a post-it (taller if more is written on it)
@@ -151,9 +187,9 @@ export const COMPONENT_TYPES = nodeDefinitions
 const definitionsByType = new Map(nodeDefinitions.map((definition) => [definition.type, definition]));
 
 // Node types that only come from the catalog (not in the components list)
-const catalogNodeTypes: Record<string, { label: string; resourceKey: string }> = {
-  system: { label: 'System', resourceKey: 'system' },
-  'context-domain': { label: 'Domain', resourceKey: 'domain' },
+const catalogNodeTypes: Record<string, { label: string; resourceKey: string; firstLevel: 1 | 2 | 3 }> = {
+  system: { label: 'System', resourceKey: 'system', firstLevel: 1 },
+  'context-domain': { label: 'Domain', resourceKey: 'domain', firstLevel: 1 },
 };
 
 export const getNodeDefinition = (type?: string) => (type ? definitionsByType.get(type) : undefined);
@@ -188,6 +224,10 @@ export const getNoteLevel = (node: { type?: string; data: Record<string, unknown
 export const isOnLevel = (node: { type?: string; data: Record<string, unknown> }, level: 1 | 2 | 3) =>
   node.type !== 'note' || getNoteLevel(node) === level;
 
+/** Whether a level of detail shows a kind of node (so it can be added there, and stay there) */
+export const isShownOnLevel = (type: string | undefined, level: 1 | 2 | 3) =>
+  level >= (getNodeDefinition(type)?.firstLevel ?? catalogNodeTypes[type ?? '']?.firstLevel ?? 3);
+
 /** Notes and text: written on the canvas itself (their text is their data, not a resource with a name) */
 export const isWrittenOnCanvas = (type?: string) => type === 'note' || type === 'text';
 

package/eventcatalog/src/features/studio/pages/index.astro

@@ -4,7 +4,8 @@ import { ChevronDown, ChevronLeft, ChevronRight, Copy, EllipsisVertical, Pencil,
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import StudioNotice from '../components/StudioNotice.astro';
 import { buildUrl } from '@utils/url-builder';
-import { CANVAS_STATUSES, MAX_TITLE_LENGTH, type CanvasStatus } from '../canvas-doc';
+import { CANVAS_STATUSES, type CanvasStatus } from '../canvas-doc';
+import { MAX_TITLE_LENGTH } from '../limits';
 import { MAX_NAME_LENGTH } from '../identity';
 import { CANVAS_STATUS_LOOK, STATUS } from '../components/status';
 import { CANVASES_API_PATH } from '../api/canvases-api';

package/eventcatalog/src/features/studio/server/canvas-mcp.ts

@@ -427,7 +427,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       const { nodes, edges } = await runtime.withCanvas(id, readCanvas);
       const positions = await getLayoutPositions(nodes, edges);
       await playLayout(asAgent(id, name).stage, positions);
-      return text({ laidOut: positions.size });
+      return text({ laidOut: positions.nodes.size });
     }
   );
 

package/eventcatalog/src/features/studio/server/runtime.ts

@@ -6,16 +6,18 @@ import type { XYPosition } from '@xyflow/react';
 import type { AgentPresence } from '../agent-choreography';
 import {
   CANVAS_DELETED_REASON,
-  MAX_TITLE_LENGTH,
+  addCanvasContent,
   canvasDocumentName,
   canvasIdFromDocumentName,
   getCanvasMaps,
   readMeta,
   setMeta,
   getCanvasStatus,
+  type CanvasContent,
   type CanvasStatus,
 } from '../canvas-doc';
 import { getCanvasPreview, type CanvasPreview } from '../canvas-preview';
+import { MAX_TITLE_LENGTH } from '../limits';
 import { fromBase64, toBase64, type SyncRequest, type SyncResponse } from '../tool-sync';
 import config from '../../../utils/eventcatalog-config/source';
 import { isAuthEnabled } from '../../../utils/feature';
@@ -299,10 +301,16 @@ export class StudioRuntime {
     return true;
   }
 
-  /** Starts a canvas with a title, recording when and by whom (a person, or an agent). Returns its id. */
-  async createCanvas(started: { title?: string; createdBy?: string }) {
+  /**
+   * Starts a canvas with a title, recording when and by whom (a person, or an agent), and what's on it to begin
+   * with, if anything. Returns its id.
+   */
+  async createCanvas(started: { title?: string; createdBy?: string }, content?: CanvasContent) {
     const canvasId = crypto.randomUUID();
-    await this.withCanvas(canvasId, (doc) => setStarted(doc, started));
+    await this.withCanvas(canvasId, (doc) => {
+      setStarted(doc, started);
+      if (content) addCanvasContent(doc, content);
+    });
     return canvasId;
   }
 

package/eventcatalog/src/utils/node-graphs/domain-levels-node-graph.ts

@@ -267,7 +267,7 @@ export const buildDomainGraph = ({
         draggable: false,
         selectable: false,
         data: {
-          domain: { name: d.data.name, version: d.data.version },
+          domain: { id: d.data.id, name: d.data.name, version: d.data.version },
           // The domain viewed may itself be a subdomain of another
           subdomain: !!parentId || parentDomainOf.has(d.data.id),
           isFocused: !parentId,
@@ -309,7 +309,7 @@ export const buildDomainGraph = ({
         position: { x: 0, y: 0 },
         ...(parentId ? { parentId } : {}),
         data: {
-          domain: { name: other.data.name, version: other.data.version },
+          domain: { id: other.data.id, name: other.data.name, version: other.data.version },
           subdomain: !!parentId,
           isFocused: false,
           otherDomain: true,
@@ -375,7 +375,7 @@ export const buildDomainGraph = ({
         type: 'system-group',
         parentId: domainGroup,
         position: { x: 0, y: 0 },
-        data: { system: { name: system.data.name, version: system.data.version } },
+        data: { system: { id: system.data.id, name: system.data.name, version: system.data.version } },
       });
     }
     addNodes(graph.nodes);

package/eventcatalog/src/utils/node-graphs/node-resource.ts

@@ -0,0 +1,67 @@
+/**
+ * The catalog resource a diagram node shows, for the node types the node graphs build. Has no imports so it can
+ * be shared by the server and the browser (the visualiser's "Open in Studio", the MCP App views).
+ */
+
+// The collection each node type shows a resource of
+const NODE_COLLECTIONS: Record<string, string> = {
+  service: 'services',
+  services: 'services',
+  agent: 'agents',
+  agents: 'agents',
+  event: 'events',
+  events: 'events',
+  command: 'commands',
+  commands: 'commands',
+  query: 'queries',
+  queries: 'queries',
+  channel: 'channels',
+  channels: 'channels',
+  flow: 'flows',
+  flows: 'flows',
+  data: 'containers',
+  containers: 'containers',
+  'data-products': 'data-products',
+  domain: 'domains',
+  domains: 'domains',
+  'context-domain': 'domains',
+  'domain-group': 'domains',
+  system: 'systems',
+  systems: 'systems',
+  'system-group': 'systems',
+};
+
+// Where each node type keeps the resource it shows
+const RESOURCE_DATA_KEYS = [
+  'service',
+  'agent',
+  'message',
+  'channel',
+  'data',
+  'dataProduct',
+  'flow',
+  'entity',
+  'domain',
+  'system',
+  'custom',
+];
+
+type DiagramNode = { type?: string; data?: Record<string, unknown> };
+type ResourceDetails = { id?: unknown; version?: unknown; [key: string]: unknown };
+
+/** The resource a node shows, as in its data: the fields shown, or the catalog entry's data (if it holds the entry) */
+export const getNodeResourceDetails = (node: DiagramNode): ResourceDetails | undefined => {
+  const data = node.data ?? {};
+  const resource = RESOURCE_DATA_KEYS.map((key) => data[key]).find(Boolean) as
+    | (ResourceDetails & { data?: ResourceDetails })
+    | undefined;
+  return resource?.data ?? resource;
+};
+
+/** The catalog resource a node shows (its collection, id and version), if it shows one */
+export const getNodeCatalogResource = (node: DiagramNode): { collection: string; id: string; version?: string } | undefined => {
+  const collection = NODE_COLLECTIONS[node.type ?? ''];
+  const details = getNodeResourceDetails(node);
+  if (!collection || typeof details?.id !== 'string') return undefined;
+  return { collection, id: details.id, ...(typeof details.version === 'string' && { version: details.version }) };
+};