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

package/eventcatalog/src/features/studio/document-name.ts

@@ -0,0 +1,7 @@
+// Canvases' documents on the collaboration server are named `design:<canvasId>` (scripts and peers join by it)
+const DOCUMENT_PREFIX = 'design:';
+export const canvasDocumentName = (canvasId: string) => `${DOCUMENT_PREFIX}${canvasId}`;
+export const canvasIdFromDocumentName = (name: string) =>
+  name.startsWith(DOCUMENT_PREFIX) ? name.slice(DOCUMENT_PREFIX.length) : undefined;
+/** Why the collaboration server refuses a canvas that was deleted (told to anyone who still has it open) */
+export const CANVAS_DELETED_REASON = 'canvas-deleted';

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

@@ -2,7 +2,7 @@ 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';
+import { DEFAULT_NODE_SIZE, isCatalogCollection, isGroupType } from '@eventcatalog/visualiser/studio';
 
 /**
  * A canvas started from a diagram (the visualiser's "Open in Studio"): the catalog resources and actors it shows,

package/eventcatalog/src/features/studio/hooks/presence-sender.ts

@@ -2,6 +2,11 @@ import type { Awareness } from 'y-protocols/awareness';
 
 /** About 30 times a second, like Excalidraw and tldraw: smooth for others, without a message on every mousemove */
 export const PRESENCE_INTERVAL_MS = 33;
+/**
+ * Once a second when nobody else is on the canvas (people or agents), as tldraw does: nobody sees it, and the
+ * collaboration server sends every one back. Someone arriving gets what's waiting straight away.
+ */
+export const ALONE_INTERVAL_MS = 1000;
 
 export type PresenceSender = {
   /** Share these fields of our presence: straight away if nothing was sent lately, otherwise with the next send */
@@ -16,10 +21,15 @@ export type PresenceSender = {
  * sends the whole state on every change, so fields changed together (the pointer and the node it drags) go in one
  * message, and the latest value always goes out (the pointer stops where it really stopped).
  */
-export function createPresenceSender(awareness: Awareness, intervalMs = PRESENCE_INTERVAL_MS): PresenceSender {
+export function createPresenceSender(
+  awareness: Awareness,
+  intervalMs = PRESENCE_INTERVAL_MS,
+  aloneIntervalMs = ALONE_INTERVAL_MS
+): PresenceSender {
   let pending: Record<string, unknown> | undefined;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let lastSent = -Infinity;
+  const alone = () => awareness.getStates().size <= 1;
 
   const flush = () => {
     clearTimeout(timer);
@@ -30,17 +40,24 @@ export function createPresenceSender(awareness: Awareness, intervalMs = PRESENCE
     lastSent = performance.now();
     awareness.setLocalState({ ...awareness.getLocalState(), ...fields });
   };
+  // Someone arrived: they get what's waiting now, not at the next (slower) send
+  const onChange = ({ added }: { added: number[] }) => {
+    if (pending && added.some((id) => id !== awareness.clientID)) flush();
+  };
+  awareness.on('change', onChange);
 
   return {
     send: (fields) => {
       pending = { ...pending, ...fields };
       if (timer) return;
-      timer = setTimeout(flush, Math.max(0, intervalMs - (performance.now() - lastSent)));
+      const interval = alone() ? aloneIntervalMs : intervalMs;
+      timer = setTimeout(flush, Math.max(0, interval - (performance.now() - lastSent)));
     },
     flush,
     destroy: () => {
       clearTimeout(timer);
       pending = undefined;
+      awareness.off('change', onChange);
     },
   };
 }

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

@@ -2,8 +2,14 @@ import { useEffect, useRef, useState } from 'react';
 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 {
+  replyToThread,
+  setThreadResolved,
+  type Author,
+  CANVAS_STATUSES,
+  setCanvasStatus,
+  CATALOG_COLLECTIONS,
+} from '@eventcatalog/visualiser/studio';
 import {
   ADD_TO_CANVAS_DESCRIPTION,
   describeCanvas,
@@ -284,7 +290,7 @@ const createCanvasTools = (get: () => CanvasWebMcpOptions, getStage: () => Agent
       name: 'layout_canvas',
       title: 'Tidy the canvas',
       description:
-        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes), for everyone on it. It moves everything, including what people placed themselves, so only use it when the user asks to tidy up: add_to_canvas already places what you add next to what it connects to.",
+        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes), for everyone on it. Call it once when you finish a round of changes, before you hand back to the user, so the canvas is tidy for everyone, and whenever the user asks to tidy up. Don't call it after every change (add_to_canvas already places what you add next to what it connects to while you work), and skip it if the user asked to keep the layout as it is: it moves everything, including what people placed themselves.",
       input: z.object({}),
       execute: async () => {
         await get().reorder();

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

@@ -13,9 +13,9 @@ import {
   type Author,
   type CommentAnchor,
   type Thread,
-} from '../canvas-doc';
+} from '@eventcatalog/visualiser/studio';
 
-export type { Author, CommentAnchor, Message, Thread } from '../canvas-doc';
+export type { Author, CommentAnchor, Message, Thread } from '@eventcatalog/visualiser/studio';
 
 /** Comment threads in the shared canvas document */
 export function useComments(doc: Y.Doc | null, author: Author) {

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

@@ -15,8 +15,6 @@ import {
 import {
   addNodes,
   buildNode,
-  CANVAS_DELETED_REASON,
-  canvasDocumentName,
   connectNodes,
   deleteEdges,
   deleteNodes as deleteNodesInDoc,
@@ -41,15 +39,36 @@ import {
   readLevelLayout,
   setLevelPlaces,
   type StatusChange,
-  setNodeParent,
+  setNodeParents,
   type RenderedSizes,
   updateNodeData as updateNodeDataInDoc,
-} from '../canvas-doc';
+  keepDragged,
+  LOCAL_EDGE_KEYS,
+  LOCAL_NODE_KEYS,
+  patchShared,
+  withPositions,
+  createSmoother,
+  containerFor,
+  toRelativePosition,
+  type NodePreview,
+  type LayoutResult,
+  canGoInContainer,
+  getNodeDefinition,
+  isGroupType,
+  createHotspot as createHotspotInDoc,
+  updateHotspot as updateHotspotInDoc,
+  deleteHotspot as deleteHotspotInDoc,
+  readHotspots,
+  getLock,
+  setLock,
+  type Hotspot,
+  type Editing,
+  addThreads,
+  addHotspots,
+  type ModelCanvasContent,
+} from '@eventcatalog/visualiser/studio';
+import { CANVAS_DELETED_REASON, canvasDocumentName } from '../document-name';
 import { applyLayout } from '../agent-choreography';
-import { keepDragged, LOCAL_EDGE_KEYS, LOCAL_NODE_KEYS, patchShared, withPositions } from '../flow-state';
-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';
 import { createPresenceSender, type PresenceSender } from './presence-sender';
 import { createPresenceStore, type PresenceStore } from './presence-store';
@@ -73,10 +92,14 @@ 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');
+/** A diagram file opened into a new canvas: what it starts with, synced, not undone (nothing to go back to) */
+const OPEN_ORIGIN = Symbol('studio-open');
 /** 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;
+/** What someone changing a note or text shows the others as they change it (see `editing` in their presence) */
+const EDITED_FIELDS = ['text', 'fontSize', 'angle'] as const;
 
 export type Status = 'connecting' | 'connected' | 'disconnected';
 export type Transport = 'websocket' | 'tools';
@@ -100,6 +123,7 @@ export function useStudioFlow({
   name,
   color,
   picture,
+  agent,
   syncViaTools,
   onLayout,
   onContainerResize,
@@ -111,6 +135,8 @@ export function useStudioFlow({
   color: string;
   /** From your sign-in provider, when you're signed in */
   picture?: string;
+  /** You're an AI agent here (e.g. a chat's canvas view, which joins as the chat's agent) */
+  agent?: boolean;
   /** 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 */
@@ -142,8 +168,14 @@ export function useStudioFlow({
   const [transport, setTransport] = useState<Transport>('websocket');
   // Someone deleted the canvas: the server closed it for everyone, and won't open it again
   const [deleted, setDeleted] = useState(false);
+  // What's flagged on the canvas (risks, problems, the key parts), on nodes or at places
+  const [hotspots, setHotspots] = useState<Hotspot[]>([]);
+  // Who locked the canvas (for everyone on it), if it's locked
+  const [lockedBy, setLockedBy] = useState<string | null>(null);
+  // The server's copy of the canvas has arrived (what's on it is known, e.g. that it's empty)
+  const [synced, setSynced] = useState(false);
   const user = useRef<Author>({ name, color });
-  user.current = { name, color, ...(picture && { picture }) };
+  user.current = { name, color, ...(picture && { picture }), ...(agent && { agent }) };
   const onLayoutRef = useRef(onLayout);
   onLayoutRef.current = onLayout;
   const onContainerResizeRef = useRef(onContainerResize);
@@ -156,7 +188,14 @@ export function useStudioFlow({
     setEdges([]);
 
     const doc = new Y.Doc();
-    const { nodes: yNodes, edges: yEdges, threads: yThreads, meta: yMeta, levelLayouts: yLevelLayouts } = getCanvasMaps(doc);
+    const {
+      nodes: yNodes,
+      edges: yEdges,
+      threads: yThreads,
+      meta: yMeta,
+      levelLayouts: yLevelLayouts,
+      hotspots: yHotspots,
+    } = 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) => {
@@ -174,8 +213,13 @@ export function useStudioFlow({
       if (event.keysChanged.has('status') || event.keysChanged.has('statusHistory'))
         setCanvasStatusState({ status: getCanvasStatus(meta), history: meta.statusHistory ?? [] });
       if (event.keysChanged.has('layoutAt')) onLayoutRef.current?.();
+      if (event.keysChanged.has('lockedBy')) setLockedBy(getLock(doc));
     };
     yMeta.observe(syncMeta);
+    setLockedBy(null);
+    const syncHotspots = () => setHotspots(readHotspots(doc));
+    yHotspots.observe(syncHotspots);
+    setHotspots([]);
     setTitle(undefined);
     setStructureKey('');
     setDiagramLevels(undefined);
@@ -249,6 +293,7 @@ export function useStudioFlow({
         // Open isn't connected until the server lets us in (onAuthenticated)
         if (!stopToolSync) setStatus(status === 'connected' && !letIn ? 'connecting' : (status as Status));
       },
+      onSynced: ({ state }) => setSynced(state),
       onAuthenticated: () => {
         socketConnected = letIn = true;
         if (!stopToolSync) setStatus('connected');
@@ -268,6 +313,7 @@ export function useStudioFlow({
     });
     setTransport('websocket');
     setDeleted(false);
+    setSynced(false);
 
     // Back online, or back on the tab: reconnect now rather than when the next retry is due
     const reconnect = () => {
@@ -285,7 +331,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, yLevelLayouts], {
+    const undoManager = new Y.UndoManager([yNodes, yEdges, yThreads, yLevelLayouts, yHotspots], {
       captureTimeout: 500,
       trackedOrigins: new Set([null, LOCAL_ORIGIN]),
     });
@@ -302,6 +348,13 @@ export function useStudioFlow({
     // 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>>();
+    // Shown gliding, a step a frame: at most one update a frame however many people drag (each presence arriving
+    // was an update of its own: ~5 a frame with 7 people dragging), and smooth between their ~30 updates a second.
+    // Not what's been dropped since (its drop is in the document, see syncNodes).
+    const glide = createSmoother((shown) => {
+      const moved = new Map([...shown].filter(([id]) => remoteMoves.has(id)));
+      if (moved.size) setNodes((local) => withPositions(local, moved));
+    });
     const syncMoves = (_: unknown, origin: unknown) => {
       if (origin === 'local') return;
       const next = new Map<string, XYPosition>();
@@ -309,10 +362,10 @@ export function useStudioFlow({
         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 moved = [...next].some(([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 (moved || dropped.length) glide.set(next);
       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(() => {
@@ -327,6 +380,40 @@ export function useStudioFlow({
     };
     awareness.on('change', syncMoves);
 
+    // What others are writing on notes and text, and how they're scaling and turning text, as they do it (from their
+    // presence): shown on just those nodes, and back to what the document has when they're done (their result is
+    // written to the document before their presence is cleared, so it doesn't go back in between)
+    let remoteEdits = '';
+    let remoteEdited = new Set<string>();
+    const syncEdits = (_: unknown, origin: unknown) => {
+      if (origin === 'local') return;
+      const edits = new Map<string, Record<string, unknown>>();
+      awareness.getStates().forEach((state, id) => {
+        const editing = state.editing as Editing | null | undefined;
+        if (id === doc.clientID || !editing?.id) return;
+        const { id: nodeId, ...fields } = editing;
+        edits.set(nodeId, fields);
+      });
+      const key = JSON.stringify([...edits]);
+      if (key === remoteEdits) return;
+      remoteEdits = key;
+      const before = remoteEdited;
+      remoteEdited = new Set(edits.keys());
+      setNodes((local) => {
+        let next: Node[] | undefined;
+        local.forEach((node, index) => {
+          const edit = edits.get(node.id);
+          const savedData = before.has(node.id) ? yNodes.get(node.id)?.data : undefined;
+          const changes = edit ?? (savedData && Object.fromEntries(EDITED_FIELDS.map((field) => [field, savedData[field]])));
+          if (!changes || Object.entries(changes).every(([field, value]) => node.data[field] === value)) return;
+          next ??= [...local];
+          next[index] = { ...node, data: { ...node.data, ...changes } };
+        });
+        return next ?? local;
+      });
+    };
+    awareness.on('change', syncEdits);
+
     // 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;
@@ -362,12 +449,15 @@ export function useStudioFlow({
       window.removeEventListener('online', reconnect);
       document.removeEventListener('visibilitychange', onVisibilityChange);
       awareness.off('change', syncMoves);
+      awareness.off('change', syncEdits);
+      glide.stop();
       sender.destroy();
       stopToolSync?.();
       yNodes.unobserve(syncNodes);
       yLevelLayouts.unobserve(syncLevelLayouts);
       yEdges.unobserve(syncEdges);
       yMeta.unobserve(syncMeta);
+      yHotspots.unobserve(syncHotspots);
       doc.off('afterTransaction', reopenOnEdit);
       doc.off('afterTransaction', syncStructure);
       presenceStore.destroy();
@@ -535,11 +625,11 @@ export function useStudioFlow({
     []
   );
 
-  /** Add a node of a registry type, centred on a canvas position (in a container, if asked) */
+  /** Add a node of a component (its type, or its key in the components list), centred on a canvas position (in a container, if asked) */
   const addNode = useCallback(
-    (type: string, center: XYPosition, inside?: string) => {
-      const definition = getNodeDefinition(type);
-      return definition ? insertNode(type, definition.createData(), center, undefined, inside) : undefined;
+    (component: string, center: XYPosition, inside?: string) => {
+      const definition = getNodeDefinition(component);
+      return definition ? insertNode(definition.type, definition.createData(), center, undefined, inside) : undefined;
     },
     [insertNode]
   );
@@ -575,13 +665,12 @@ export function useStudioFlow({
     []
   );
 
-  /** 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) =>
+  /** Puts nodes in containers (or takes them out) together, e.g. a selection dropped in one, as one change */
+  const setParents = useCallback(
+    (moves: { id: string; parentId: string | undefined; at?: XYPosition }[]) =>
       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, renderedSizes());
+        return setNodeParents(doc, moves, renderedSizes());
       }),
     []
   );
@@ -605,6 +694,47 @@ export function useStudioFlow({
     sharedRef.current?.sender.send({ viewport });
   }, []);
 
+  /**
+   * The note or text being changed here, as it changes (what's written, a text's size and angle), for the others to
+   * see as it happens; `null` when done (after the result is saved), sent straight away
+   */
+  const sendEditing = useCallback((editing: Editing | null) => {
+    const sender = sharedRef.current?.sender;
+    if (!sender) return;
+    sender.send({ editing: editing && { ...editing, ...(editing.text !== undefined && { text: editing.text.slice(0, 2000) }) } });
+    if (!editing) sender.flush();
+  }, []);
+
+  /**
+   * What a diagram file opened into this (new) canvas starts with: its nodes and connections, comments, hotspots and
+   * where things are on L1 and L2, in one change that isn't undone
+   */
+  const addContent = useCallback(
+    (content: ModelCanvasContent) =>
+      withDoc((doc) => {
+        addNodes(doc, content.nodes, content.edges);
+        if (content.threads?.length) addThreads(doc, content.threads);
+        if (content.hotspots?.length) addHotspots(doc, content.hotspots);
+        setLevelPlaces(doc, 1, content.levelLayouts[1]);
+        setLevelPlaces(doc, 2, content.levelLayouts[2]);
+      }, OPEN_ORIGIN),
+    []
+  );
+
+  // ---- Hotspots and the lock ----
+
+  const createHotspot = useCallback(
+    (hotspot: Omit<Hotspot, 'id' | 'createdAt'>) => withDoc((doc) => createHotspotInDoc(doc, hotspot)),
+    []
+  );
+  const updateHotspot = useCallback(
+    (id: string, fields: Parameters<typeof updateHotspotInDoc>[2]) => withDoc((doc) => updateHotspotInDoc(doc, id, fields)),
+    []
+  );
+  const deleteHotspot = useCallback((id: string) => withDoc((doc) => deleteHotspotInDoc(doc, id)), []);
+  /** Locks the canvas for everyone (by a name), or unlocks it (null): looked at, not changed */
+  const setLocked = useCallback((by: string | null) => withDoc((doc) => setLock(doc, by), STATUS_ORIGIN), []);
+
   return {
     nodes,
     edges,
@@ -625,7 +755,7 @@ export function useStudioFlow({
     levelLayouts,
     setLevelLayout,
     insertNodes,
-    setParent,
+    setParents,
     title,
     diagramLevels,
     structureKey,
@@ -634,6 +764,15 @@ export function useStudioFlow({
     changeStatus,
     transport,
     deleted,
+    hotspots,
+    createHotspot,
+    updateHotspot,
+    deleteHotspot,
+    lockedBy,
+    setLocked,
+    sendEditing,
+    synced,
+    addContent,
     undo,
     redo,
     ...history,

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

@@ -1,6 +1,9 @@
 // Who you are in Studio: the name you give on your first visit, kept in this browser and used on every canvas
-const COLORS = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#3b82f6', '#8b5cf6', '#ec4899'];
+/** The colours people can go by (as Studio on the web's): on their pointer, avatar and comments */
+export const PERSON_COLORS = ['#ef4444', '#f97316', '#eab308', '#22c55e', '#06b6d4', '#3b82f6', '#8b5cf6', '#ec4899'];
+const COLORS = PERSON_COLORS;
 const NAME_KEY = 'eventcatalog-studio-name';
+const COLOR_KEY = 'eventcatalog-studio-color';
 /** Names people give are at most this long */
 export const MAX_NAME_LENGTH = 60;
 
@@ -35,3 +38,22 @@ export const colorForName = (name: string) => {
   for (const char of name) hash = (hash * 31 + char.charCodeAt(0)) | 0;
   return COLORS[Math.abs(hash) % COLORS.length];
 };
+
+/** The colour you picked, kept in this browser (else it follows from your name) */
+export const getStoredColor = () => {
+  try {
+    const color = localStorage.getItem(COLOR_KEY);
+    return color && PERSON_COLORS.includes(color) ? color : null;
+  } catch {
+    return null;
+  }
+};
+
+export const storeColor = (color: string) => {
+  try {
+    localStorage.setItem(COLOR_KEY, color);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/eventcatalog/src/features/studio/pages/[id].astro

@@ -1,7 +1,8 @@
 ---
 // Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
 import '@eventcatalog/visualiser/styles-core.css';
-import '../studio.css';
+import '@eventcatalog/visualiser/studio.css';
+import '@eventcatalog/visualiser/studio-fonts.css';
 import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
 import { buildUrl } from '@utils/url-builder';
 import StudioDesigner from '../components/StudioDesigner';

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

@@ -4,10 +4,9 @@ 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, type CanvasStatus } from '../canvas-doc';
+import { CANVAS_STATUSES, CANVAS_STATUS_LOOK, STATUS, type CanvasStatus } from '@eventcatalog/visualiser/studio';
 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';
 import { startStudio, type CanvasSummary } from '../server/runtime';
 import { getSignedInUser, isSignedIn } from '../server/sign-in';

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

@@ -21,10 +21,10 @@ import {
   setCanvasStatus,
   setThreadResolved,
   type Author,
-} from '../canvas-doc';
+  getLayoutPositions,
+} from '@eventcatalog/visualiser/studio';
 import { ADD_TO_CANVAS_DESCRIPTION, describeCanvas, edgeSpecsSchema, indexCatalog, nodeSpecsSchema } from '../canvas-actions';
 import { getCatalogResources } from '../catalog-resources';
-import { getLayoutPositions } from '../layout';
 import {
   playAddToCanvas,
   playComment,
@@ -35,7 +35,8 @@ import {
   playUpdateNode,
   type AgentStage,
 } from '../agent-choreography';
-import { STUDIO_SOCKET_PATH, findStudioRuntime, type AgentIdentity } from './runtime';
+import { STUDIO_SOCKET_PATH, findStudioRuntime } from './runtime';
+import { getAgent } from '../agents';
 import { addToolIcons } from './tool-icons';
 
 /**
@@ -46,21 +47,11 @@ import { addToolIcons } from './tool-icons';
 
 const loadCanvasView = getMcpAppViewLoader('canvas');
 
-const AGENT_COLORS: Record<string, string> = { ChatGPT: '#10a37f', Claude: '#d97757' };
-
 // The canvases entrypoint's icon (OpenAI MCP extensions: a 20x20, monochrome SVG in currentColor, 1.33px strokes)
 const CANVAS_ICON_SVG =
   '<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.33" stroke-linecap="round" stroke-linejoin="round"><rect x="2.5" y="3.5" width="5.5" height="4.5" rx="1"/><rect x="12" y="3.5" width="5.5" height="4.5" rx="1"/><rect x="12" y="12" width="5.5" height="4.5" rx="1"/><path d="M8 5.75h4M14.75 8v4"/></svg>';
 const CANVAS_ICON = { src: `data:image/svg+xml;base64,${btoa(CANVAS_ICON_SVG)}`, mimeType: 'image/svg+xml', sizes: ['20x20'] };
 
-/** Who the agent is, from what it tells us or its client's user agent */
-const getAgent = (agentName: string | undefined, userAgent = ''): AgentIdentity => {
-  const name =
-    agentName?.trim() ||
-    (/openai|chatgpt/i.test(userAgent) ? 'ChatGPT' : /claude|anthropic/i.test(userAgent) ? 'Claude' : 'AI agent');
-  return { name, color: AGENT_COLORS[name] ?? '#8b5cf6' };
-};
-
 const text = (value: unknown, isError = false) => ({
   content: [{ type: 'text' as const, text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
   ...(isError && { isError }),
@@ -151,12 +142,6 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       input: {
         canvasId: canvasId.optional(),
         title: z.string().optional().describe('For a new canvas: what it is for'),
-        userName: z
-          .string()
-          .optional()
-          .describe(
-            'The name of the person you are working with, if you know it: others on the canvas see them by this name. Leave it out if you do not know it.'
-          ),
         agentName,
       },
     },
@@ -170,7 +155,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     annotations: writes,
     errorMessage: 'Failed to open the canvas',
     load: async (params) => {
-      const { title: newTitle, agentName: name, userName } = params as { title?: string; agentName?: string; userName?: string };
+      const { title: newTitle, agentName: name } = params as { title?: string; agentName?: string };
 
       // Opened without a canvas (e.g. from an entrypoint): the canvases to pick from, or start one
       if (!params.canvasId && !newTitle) {
@@ -207,7 +192,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
         socketUrl,
         canvasUrl: canvasUrl(id),
         mcpUrl: `${catalogUrl}${buildUrl('/docs/mcp', true)}`,
-        userName,
+        agent: getAgent(name, userAgent),
       };
       return {
         forModel: {
@@ -418,7 +403,7 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
     {
       title: 'Tidy a canvas',
       description:
-        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes); everyone on it sees the nodes glide into place. It moves everything, including what people placed themselves, so only use it when the user asks to tidy up: addToCanvas already places what you add next to what it connects to.",
+        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes); everyone on it sees the nodes glide into place. Call it once when you finish a round of changes, before you hand back to the user, so the canvas is tidy for everyone, and whenever the user asks to tidy up. Don't call it after every change (addToCanvas already places what you add next to what it connects to while you work), and skip it if the user asked to keep the layout as it is: it moves everything, including what people placed themselves.",
       inputSchema: z.object({ canvasId, agentName }),
       annotations: writes,
     },

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

@@ -5,17 +5,15 @@ import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwareness
 import type { XYPosition } from '@xyflow/react';
 import type { AgentPresence } from '../agent-choreography';
 import {
-  CANVAS_DELETED_REASON,
   addCanvasContent,
-  canvasDocumentName,
-  canvasIdFromDocumentName,
   getCanvasMaps,
   readMeta,
   setMeta,
   getCanvasStatus,
   type CanvasContent,
   type CanvasStatus,
-} from '../canvas-doc';
+} from '@eventcatalog/visualiser/studio';
+import { CANVAS_DELETED_REASON, canvasDocumentName, canvasIdFromDocumentName } from '../document-name';
 import { getCanvasPreview, type CanvasPreview } from '../canvas-preview';
 import { MAX_TITLE_LENGTH } from '../limits';
 import { fromBase64, toBase64, type SyncRequest, type SyncResponse } from '../tool-sync';
@@ -33,7 +31,8 @@ const AGENT_PRESENCE_TTL_MS = 25_000;
 // Application close codes are 4000-4999
 const CANVAS_DELETED_CLOSE_CODE = 4410;
 
-export type AgentIdentity = { name: string; color: string };
+import type { AgentIdentity } from '../agents';
+export type { AgentIdentity };
 export type CanvasSummary = {
   canvasId: string;
   title?: string;

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.0.0-beta.12",
+  "version": "5.0.0-beta.13",
   "publishConfig": {
     "access": "public"
   },
@@ -141,8 +141,8 @@
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
     "@eventcatalog/linter": "1.2.0-beta.2",
-    "@eventcatalog/sdk": "2.30.0-beta.1",
-    "@eventcatalog/visualiser": "^5.0.0-beta.5"
+    "@eventcatalog/visualiser": "^5.0.0-beta.6",
+    "@eventcatalog/sdk": "2.30.0-beta.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",