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

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,
@@ -25,7 +23,9 @@ import {
   fitGroupToChildren,
   getCanvasMaps,
   moveNode,
+  placeNode,
   changesNodesOrEdges,
+  getStructureKey,
   getCanvasStatus,
   readMeta,
   reopenIfDecided,
@@ -34,16 +34,41 @@ import {
   setMeta,
   type Author,
   type CanvasStatus,
+  type DiagramLevels,
+  type LevelPlace,
+  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 { findGroupAtPoint, 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';
@@ -67,6 +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';
@@ -90,6 +123,7 @@ export function useStudioFlow({
   name,
   color,
   picture,
+  agent,
   syncViaTools,
   onLayout,
   onContainerResize,
@@ -101,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 */
@@ -121,12 +157,25 @@ 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
   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);
@@ -139,16 +188,41 @@ 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,
+      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) => {
+        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?.();
+      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);
     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 +243,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);
@@ -213,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');
@@ -232,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 = () => {
@@ -249,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], {
+    const undoManager = new Y.UndoManager([yNodes, yEdges, yThreads, yLevelLayouts, yHotspots], {
       captureTimeout: 500,
       trackedOrigins: new Set([null, LOCAL_ORIGIN]),
     });
@@ -266,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>();
@@ -273,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(() => {
@@ -291,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;
@@ -326,12 +449,17 @@ 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();
       undoManager.destroy();
       provider.destroy();
@@ -384,10 +512,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 +602,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 +625,11 @@ export function useStudioFlow({
     []
   );
 
-  /** Add a node of a registry type, centred on a canvas position */
+  /** 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) => {
-      const definition = getNodeDefinition(type);
-      return definition ? insertNode(type, definition.createData(), center) : undefined;
+    (component: string, center: XYPosition, inside?: string) => {
+      const definition = getNodeDefinition(component);
+      return definition ? insertNode(definition.type, definition.createData(), center, undefined, inside) : undefined;
     },
     [insertNode]
   );
@@ -510,6 +644,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(
@@ -525,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());
       }),
     []
   );
@@ -555,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,
@@ -572,14 +752,27 @@ export function useStudioFlow({
     updateNodeData,
     deleteNodes,
     applyPositions,
+    levelLayouts,
+    setLevelLayout,
     insertNodes,
-    setParent,
+    setParents,
     title,
+    diagramLevels,
+    structureKey,
     rename,
     canvasStatus,
     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/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/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,9 +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, MAX_TITLE_LENGTH, 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,
     },
@@ -427,7 +412,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

@@ -5,17 +5,17 @@ import { Awareness, applyAwarenessUpdate, encodeAwarenessUpdate, removeAwareness
 import type { XYPosition } from '@xyflow/react';
 import type { AgentPresence } from '../agent-choreography';
 import {
-  CANVAS_DELETED_REASON,
-  MAX_TITLE_LENGTH,
-  canvasDocumentName,
-  canvasIdFromDocumentName,
+  addCanvasContent,
   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';
 import config from '../../../utils/eventcatalog-config/source';
 import { isAuthEnabled } from '../../../utils/feature';
@@ -31,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;
@@ -299,10 +300,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;
   }