@eventcatalog/core 5.7.0 → 5.7.2

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

@@ -97,15 +97,17 @@ export const buildContainer = (resource: CatalogResource, center: { x: number; y
  * A domain or system as a container with everything it holds in the catalog: its systems (as containers too)
  * and services, and the messages and data stores of those services, so every level of detail (L1 to L3) has
  * something to show. Laid out with the visualiser's layout and centred on a point, with the connections between
- * them and to related resources already on the canvas. Resources already on the canvas aren't added again.
+ * them and to related resources already on the canvas. Resources already on the canvas aren't added again, nor
+ * any in `alsoAdding` (by catalog key: added some other way at the same time, e.g. by an agent in the same call).
  */
 export const buildContainerWithContents = async (
   resource: CatalogResource,
   center: { x: number; y: number },
   catalog: { resourcesByKey: Map<string, CatalogResource>; relationsByKey: Map<string, CatalogRelation[]> },
-  existing: Node[]
+  existing: Node[],
+  alsoAdding: ReadonlySet<string> = new Set()
 ): Promise<{ nodes: Node[]; edges: Edge[] }> => {
-  const onCanvas = new Set(existing.map((node) => getCatalogLink(node)?.key).filter(Boolean));
+  const onCanvas = new Set([...existing.map((node) => getCatalogLink(node)?.key).filter(Boolean), ...alsoAdding]);
   const root = buildContainer(resource, { x: 0, y: 0 });
   const nodes: Node[] = [root];
   const added = (key: string) => onCanvas.has(key) || nodes.some((node) => getCatalogLink(node)?.key === key);

package/eventcatalog/src/features/studio/components/CanvasHeader.tsx

@@ -10,6 +10,7 @@ import {
   Plug,
   Plus,
   Share2,
+  Sparkles,
   Trash2,
   Users,
 } from 'lucide-react';
@@ -440,6 +441,7 @@ export default memo(function CanvasHeader({
   statusHistory,
   onStatusChange,
   onDelete,
+  onDrawWithAi,
 }: {
   title?: string;
   onRetitle: (title: string) => void;
@@ -470,6 +472,8 @@ export default memo(function CanvasHeader({
   onHelp: () => void;
   /** Ask to delete the canvas (not given where it can't be, e.g. inside a chat) */
   onDelete?: () => void;
+  /** Opens the assistant to draw on the canvas (not given where there isn't one, e.g. inside a chat) */
+  onDrawWithAi?: () => void;
 }) {
   const peers = usePeople(presence);
   const agentsHere = peers.some((peer) => peer.agent);
@@ -505,6 +509,16 @@ export default memo(function CanvasHeader({
           </div>
         )}
         <ProfileMenu me={me} onRename={onRename} onRecolor={onRecolor} />
+        {onDrawWithAi && (
+          <button
+            onClick={onDrawWithAi}
+            title="Describe what to diagram and the assistant draws it here"
+            className={`${barClass} gap-2 px-3 text-sm font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:bg-[rgb(var(--ec-accent-subtle))]`}
+          >
+            <Sparkles size={16} className="text-[rgb(var(--ec-accent))]" aria-hidden />
+            Draw with AI
+          </button>
+        )}
         <button
           onClick={onShare}
           className="pointer-events-auto inline-flex h-[38px] items-center gap-2 rounded-[9px] bg-[rgb(var(--ec-page-text))] px-4 text-sm font-semibold text-[rgb(var(--ec-page-bg))] shadow-sm transition-colors hover:bg-[rgb(var(--ec-page-text)/0.85)]"

package/eventcatalog/src/features/studio/components/StudioDesigner.tsx

@@ -94,6 +94,7 @@ import {
   isGroupType,
   type Hotspot,
   type HotspotDraft,
+  type HotspotPlace,
   type HotspotFields,
   type HotspotSeverity,
   type HotspotSpot,
@@ -133,6 +134,12 @@ import ShareDialog from './ShareDialog';
 import DeleteCanvasDialog from './DeleteCanvasDialog';
 import { createCanvasThroughApi, deleteCanvasThroughApi } from '../api/client';
 import ShortcutsDialog from './ShortcutsDialog';
+import {
+  ASSISTANT_DRAWING_EVENT,
+  CANVAS_FOCUS_EVENT,
+  CANVAS_HOTSPOT_EVENT,
+  OPEN_CHAT_EVENT,
+} from '../../../components/ChatPanel/assistant-events';
 
 type CanvasProps = {
   canvasId: string;
@@ -165,6 +172,8 @@ type CanvasProps = {
   asAgent?: { name: string; color: string };
   /** Signed in with the catalog's sign-in (SSO): you're shown by this name and picture, and can't change them */
   signedInAs?: { name: string; picture?: string };
+  /** The catalog's assistant (Ask AI) is on the page: "Draw with AI" opens it to draw on the canvas */
+  assistant?: boolean;
   resources: CatalogResource[];
   relations: CatalogRelation[];
 };
@@ -198,6 +207,7 @@ type Landing = {
 };
 const DELETE_KEYS = ['Backspace', 'Delete'];
 const NO_THREADS: ReadonlySet<string> = new Set();
+const NO_HOTSPOTS: ReadonlySet<string> = new Set();
 // React Flow's warnings, except that a handle has no node: the left panel's drag previews draw nodes off the canvas
 const onFlowError = (code: string, message: string) => {
   if (code !== '010') console.warn(message);
@@ -339,6 +349,9 @@ export default function StudioDesigner({ asAgent, signedInAs, ...props }: Canvas
   );
 }
 
+// The assistant's panel (ChatPanelButton, in the page header) opens on this; on a canvas it draws on it
+const openAssistant = () => window.dispatchEvent(new Event(OPEN_CHAT_EVENT));
+
 const toSocketUrl = (socketPath = DEFAULT_SOCKET_PATH) =>
   `${window.location.protocol === 'https:' ? 'wss' : 'ws'}://${window.location.host}${socketPath}`;
 
@@ -353,6 +366,7 @@ function Canvas({
   mcpUrl = '/docs/mcp',
   relayScriptPath,
   keptInMemory = false,
+  assistant = false,
   syncViaTools,
   followChanges = false,
   paletteCollapsed,
@@ -686,6 +700,8 @@ function Canvas({
   const [lastCopied, setLastCopied] = useState<ClipboardContent | null>(null);
   // Nodes to copy instead of the selection (copying from the context menu)
   const copyOnly = useRef<string[] | null>(null);
+  // Whether the menu's copy got onto the clipboard (Cut only deletes once it has)
+  const copiedFromMenu = useRef(false);
 
   /** Adds copies (as one change, so one undo takes them back) and selects them instead of what was selected */
   const paste = useStableCallback((content: ClipboardContent, place: { at: XYPosition } | { offset: XYPosition }) => {
@@ -718,6 +734,7 @@ function Canvas({
       event.clipboardData.setData('text/plain', content.nodes.map((node) => getNodeName(node.type, node.data)).join('\n'));
       pastes.current = 0;
       setLastCopied(content);
+      if (fromMenu) copiedFromMenu.current = true;
       if (event.type === 'cut') flow.deleteNodes(ids);
     };
     const onPaste = (event: ClipboardEvent) => {
@@ -973,7 +990,13 @@ function Canvas({
   // Comments that are part of the selection (selecting everything selects them too): only here, like what nodes
   // are selected. While what's selected is dragged, the ones not on a node move with it by this much.
   const [selectedThreads, setSelectedThreads] = useState<ReadonlySet<string>>(NO_THREADS);
-  const clearSelectedThreads = useCallback(() => setSelectedThreads((current) => (current.size ? NO_THREADS : current)), []);
+  // Hotspots too (selecting everything selects them, and deleting it deletes them)
+  const [selectedHotspots, setSelectedHotspots] = useState<ReadonlySet<string>>(NO_HOTSPOTS);
+  /** Comments and hotspots stop being part of the selection */
+  const clearSelectedPins = useCallback(() => {
+    setSelectedThreads((current) => (current.size ? NO_THREADS : current));
+    setSelectedHotspots((current) => (current.size ? NO_HOTSPOTS : current));
+  }, []);
   const [threadsOffset, setThreadsOffset] = useState<XYPosition | null>(null);
   const threadsShown = () => comments.threads.filter((thread) => showResolved || !thread.resolved);
   const [contextMenu, setContextMenu] = useState<ContextMenuState>(null);
@@ -1173,6 +1196,10 @@ function Canvas({
     setHotspotDraft(null);
   });
   const cancelHotspot = useCallback(() => setHotspotDraft(null), []);
+  // The hotspot being added, dragged somewhere else before it's added: onto a node, or a place on the level shown
+  const moveHotspotDraft = useStableCallback((to: HotspotPlace) =>
+    setHotspotDraft((draft) => draft && { ...(to.nodeId ? { nodeId: to.nodeId } : placeLevel()), position: to.position })
+  );
   const deleteHotspot = useStableCallback((id: string) => flow.deleteHotspot(id));
   // Dragged onto a node (they move with it), or to a place; open where it lands if it was open
   const moveHotspots = useStableCallback((ids: string[], to: { nodeId?: string; position: XYPosition }) => {
@@ -1194,8 +1221,8 @@ function Canvas({
     const width = node ? (node.measured?.width ?? node.width ?? 0) : 0;
     void setCenter(at.x + width / 2 + 120, at.y + 80, { zoom: Math.max(getZoom(), 0.8), duration: 300 });
     setHotspotDraft(null);
+    // (the list stays open, so they can go through them one by one)
     setOpenHotspot(node ? `node:${node.id}` : `place:${hotspot.id}`);
-    setListingHotspots(false);
   });
   const nameOfNode = useStableCallback((id: string) => {
     const node = nodesRef.current.find((candidate) => candidate.id === id);
@@ -1328,6 +1355,57 @@ function Canvas({
 
   const [following, setFollowing] = useState(followChanges);
   const toggleFollowing = useCallback(() => setFollowing((on) => !on), []);
+  // Asking the assistant (Ask AI) to draw on this canvas follows it while it works
+  useEffect(() => {
+    const followAssistant = (event: Event) => {
+      if ((event as CustomEvent<{ canvasId?: string }>).detail?.canvasId === canvasId) setFollowing(true);
+    };
+    window.addEventListener(ASSISTANT_DRAWING_EVENT, followAssistant);
+    return () => window.removeEventListener(ASSISTANT_DRAWING_EVENT, followAssistant);
+  }, [canvasId]);
+
+  // The assistant taking you to part of the canvas (showOnCanvas, a walkthrough's steps): zoomed to, and selected. On
+  // the canvas people edit (L3), where everything is.
+  const focusOn = useStableCallback((ids: string[]) => {
+    const nodes = lookupNodes();
+    const found = ids.filter((id) => nodes.has(id));
+    if (!found.length) return;
+    const changingLevel = levelRef.current !== 3;
+    if (changingLevel) changeLevel(3);
+    // You're looking around now: following the agent would take the camera back to its pointer a moment later
+    setFollowing(false);
+    // Once the level's switched (and drawn), if it was
+    setTimeout(
+      () => {
+        select(new Set(found));
+        void fitView({ nodes: found.map((id) => ({ id })), duration: 600, padding: 0.35, maxZoom: 1.2 });
+      },
+      changingLevel ? 400 : 0
+    );
+  });
+  useEffect(() => {
+    const focus = (event: Event) => {
+      const { canvasId: on, nodeIds } = (event as CustomEvent<{ canvasId?: string; nodeIds?: string[] }>).detail ?? {};
+      if (on === canvasId && nodeIds?.length) focusOn(nodeIds);
+    };
+    window.addEventListener(CANVAS_FOCUS_EVENT, focus);
+    return () => window.removeEventListener(CANVAS_FOCUS_EVENT, focus);
+  }, [canvasId, focusOn]);
+  // ...and to a hotspot it flagged, opened
+  const showHotspot = useStableCallback((hotspotId: string) => {
+    const hotspot = flow.hotspots.find((candidate) => candidate.id === hotspotId);
+    if (!hotspot) return;
+    setFollowing(false);
+    goToHotspot(hotspot);
+  });
+  useEffect(() => {
+    const show = (event: Event) => {
+      const { canvasId: on, hotspotId } = (event as CustomEvent<{ canvasId?: string; hotspotId?: string }>).detail ?? {};
+      if (on === canvasId && hotspotId) showHotspot(hotspotId);
+    };
+    window.addEventListener(CANVAS_HOTSPOT_EVENT, show);
+    return () => window.removeEventListener(CANVAS_HOTSPOT_EVENT, show);
+  }, [canvasId, showHotspot]);
 
   const [shareOpen, setShareOpen] = useState<false | 'choose' | 'invite'>(false);
   const openShare = useCallback(() => setShareOpen('choose'), []);
@@ -1458,6 +1536,8 @@ function Canvas({
       flow.onEdgesChange(edgesRef.current.map((edge) => ({ type: 'select', id: edge.id, selected: true })));
       // ...and the comments shown on it
       setSelectedThreads(new Set(threadsShown().map((thread) => thread.id)));
+      // ...and its hotspots (the ones on L1 and L2's own places are on those levels)
+      setSelectedHotspots(new Set(flow.hotspots.filter((hotspot) => !hotspot.level).map((hotspot) => hotspot.id)));
     },
     { preventDefault: true }
   );
@@ -1492,7 +1572,7 @@ function Canvas({
     setTool('select');
     setDraft(null);
     setOpenThreadId(null);
-    clearSelectedThreads();
+    clearSelectedPins();
     setEditingId(null);
     flow.onNodesChange(
       nodesRef.current.filter((node) => node.selected).map((node) => ({ type: 'select', id: node.id, selected: false }))
@@ -1501,11 +1581,16 @@ function Canvas({
       edgesRef.current.filter((edge) => edge.selected).map((edge) => ({ type: 'select', id: edge.id, selected: false }))
     );
   });
-  // Selected comments are deleted with what's selected (React Flow deletes the nodes and edges)
+  // Selected comments and hotspots are deleted with what's selected (React Flow deletes the nodes and edges)
   useHotkeys(DELETE_KEYS, () => {
-    if (!onCanvas() || selectedThreads.size === 0) return;
-    comments.deleteThreads([...selectedThreads]);
-    clearSelectedThreads();
+    if (!onCanvas() || (selectedThreads.size === 0 && selectedHotspots.size === 0)) return;
+    if (selectedThreads.size) comments.deleteThreads([...selectedThreads]);
+    // (hotspots, like nodes, stay on a locked canvas)
+    if (!locked) {
+      selectedHotspots.forEach((id) => flow.deleteHotspot(id));
+      if (selectedHotspots.size) setOpenHotspot(null);
+    }
+    clearSelectedPins();
   });
   /** A tool that puts something down: picked, or put back to selecting if it was already */
   const pickTool = useStableCallback((next: 'text' | 'note' | 'comment' | 'hotspot') => {
@@ -1538,7 +1623,9 @@ function Canvas({
   // A place on L1 or L2 is on that level (they're laid out on their own): what's put there says so
   const placeLevel = () => (levelRef.current === 3 ? {} : { level: levelRef.current as 1 | 2 });
   const onPaneClick = useStableCallback((event: ReactMouseEvent) => {
-    clearSelectedThreads();
+    clearSelectedPins();
+    // An open hotspot closes on a click anywhere else on the canvas
+    setOpenHotspot(null);
     if (tool === 'hand') return;
     if (commentMode && editable) return startComment(anchorAt(flowPositionOf(event)));
     // Flagging: a hotspot where it's clicked
@@ -1574,7 +1661,8 @@ function Canvas({
 
   const onNodeClick = useStableCallback((event: ReactMouseEvent, node: Node) => {
     // Clicking one node selects just it (with shift or ⌘, it's added to what's selected)
-    if (!event.shiftKey && !event.metaKey) clearSelectedThreads();
+    if (!event.shiftKey && !event.metaKey) clearSelectedPins();
+    setOpenHotspot(null);
     // Not on notes and text: they're written on, not what's being flagged or commented on
     if (isWrittenOnCanvas(node.type)) return;
     // A hotspot on it (it shows on the node, wherever it goes, on every level it's on)
@@ -1645,6 +1733,13 @@ function Canvas({
     flow.deleteNodes(menuTargets());
     setContextMenu(null);
   });
+  // Copies, then deletes, as ⌘X does: only on L3, where copying works (so it's not offered on L1 and L2)
+  const cutFromMenu = useStableCallback(() => {
+    copiedFromMenu.current = false;
+    copyFromMenu();
+    // Not copied (the browser refused, or there was nothing to copy): nothing's deleted, as with ⌘X
+    if (copiedFromMenu.current) deleteFromMenu();
+  });
 
   const openThread = useStableCallback((thread: Thread) => {
     setListingComments(false);
@@ -1761,7 +1856,7 @@ function Canvas({
                   ref={canvasRef}
                   className={`eventcatalog-visualizer studio-canvas relative flex-1 min-w-0 ${commentMode ? 'comment-mode' : ''} ${
                     transitioning ? 'is-layout-transition' : ''
-                  } ${placing || tool === 'comment' || tool === 'hotspot' ? 'is-placing' : ''} ${tool === 'hand' ? 'is-panning' : ''}`}
+                  } ${placing || tool === 'comment' || tool === 'hotspot' ? 'is-placing' : ''} ${tool === 'hotspot' ? 'is-placing-hotspot' : ''} ${tool === 'hand' ? 'is-panning' : ''}`}
                   onPointerMove={trackPointer}
                   onPointerLeave={clearPointer}
                   onDoubleClick={onCanvasDoubleClick}
@@ -1799,7 +1894,7 @@ function Canvas({
                     onNodeClick={onNodeClick}
                     onNodeDoubleClick={onNodeDoubleClick}
                     onError={onFlowError}
-                    onSelectionStart={clearSelectedThreads}
+                    onSelectionStart={clearSelectedPins}
                     onPaneContextMenu={onPaneContextMenu}
                     onNodeContextMenu={onNodeContextMenu}
                     connectionLineType={ConnectionLineType.SmoothStep}
@@ -1849,7 +1944,7 @@ function Canvas({
                       draft={hotspotDraft}
                       locked={locked}
                       movable={!locked}
-                      selectedIds={null}
+                      selectedIds={selectedHotspots.size ? selectedHotspots : null}
                       onMove={moveHotspots}
                       onDropTarget={setHotspotDropTarget}
                       onOpen={setOpenHotspot}
@@ -1858,6 +1953,7 @@ function Canvas({
                       onUpdate={flow.updateHotspot}
                       onDelete={deleteHotspot}
                       onGo={goToHotspot}
+                      onMoveDraft={moveHotspotDraft}
                     />
                   </ReactFlow>
 
@@ -1971,7 +2067,12 @@ function Canvas({
                         </button>
                       </div>
                       <div className="min-h-0 flex-1 overflow-y-auto">
-                        <HotspotList hotspots={flow.hotspots} nameOf={nameOfNode} onOpen={goToHotspot} />
+                        <HotspotList
+                          hotspots={flow.hotspots}
+                          nameOf={nameOfNode}
+                          onOpen={goToHotspot}
+                          goOnHover={!hotspotDraft}
+                        />
                       </div>
                     </div>
                   )}
@@ -2001,6 +2102,7 @@ function Canvas({
                     onAddNote={noteFromMenu}
                     onEditDetails={editFromMenu}
                     onCopy={copyFromMenu}
+                    onCut={level === 3 ? cutFromMenu : undefined}
                     onDuplicate={duplicateFromMenu}
                     onPaste={lastCopied ? pasteFromMenu : undefined}
                     onReorder={reorderFromMenu}
@@ -2033,6 +2135,7 @@ function Canvas({
                     statusHistory={flow.canvasStatus.history}
                     onStatusChange={flow.changeStatus}
                     onDelete={canvasesApiUrl ? openDelete : undefined}
+                    onDrawWithAi={assistant ? openAssistant : undefined}
                   />
 
                   {flow.deleted && !leaving && (

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

@@ -277,7 +277,7 @@ const createCanvasTools = (get: () => CanvasWebMcpOptions, getStage: () => Agent
     defineTool({
       name: 'remove_from_canvas',
       title: 'Remove from the canvas',
-      description: 'Removes nodes (and their connections) or connections. Only remove what the user asked for.',
+      description: 'Removes nodes (and their connections and hotspots) or connections. Only remove what the user asked for.',
       input: z.object({ nodeIds: z.array(z.string()).optional(), connectionIds: z.array(z.string()).optional() }),
       annotations: { consequentialHint: true },
       execute: async ({ nodeIds = [], connectionIds = [] }) => {

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

@@ -11,6 +11,7 @@ import { getCatalogResources } from '../catalog-resources';
 import { startStudio, STUDIO_SOCKET_PATH } from '../server/runtime';
 import { getSignedInUser, isSignedIn } from '../server/sign-in';
 import { CANVASES_API_PATH } from '../api/canvases-api';
+import { isEventCatalogChatVisible } from '@utils/feature';
 
 export const prerender = false;
 
@@ -59,6 +60,7 @@ const signedInAs = getSignedInUser(Astro.locals);
           mcpUrl={buildUrl('/docs/mcp', true)}
           relayScriptPath={buildUrl('/webmcp-relay/embed.js', true)}
           keptInMemory={keptInMemory}
+          assistant={isEventCatalogChatVisible()}
           signedInAs={signedInAs}
           resources={resources}
           relations={relations}

package/eventcatalog/src/features/studio/server/assistant-tools.ts

@@ -0,0 +1,207 @@
+import { tool } from 'ai';
+import { z } from 'zod';
+import { getCanvasMaps, getLayoutPositions, readCanvas } from '@eventcatalog/visualiser/studio';
+import {
+  ADD_TO_CANVAS_DESCRIPTION,
+  describeCanvas,
+  edgeSpecsSchema,
+  indexCatalog,
+  nodeSpecsSchema,
+  withNotesPlaced,
+} from '../canvas-actions';
+import { getCatalogResources } from '../catalog-resources';
+import { playAddToCanvas, playConnectAll, playHotspot, playLayout, playRemove, playUpdateNode } from '../agent-choreography';
+import { getAgent } from '../agents';
+import { agentOnCanvas } from './canvas-agent';
+import { findStudioRuntime } from './runtime';
+
+/**
+ * The assistant (Ask AI) on a Studio canvas: the canvas it was opened on, drawn on with the model the catalog has
+ * configured. Its tools play changes out like the MCP canvas tools do (same choreography), so everyone on the canvas
+ * watches the assistant's pointer draw the diagram.
+ */
+
+const ASSISTANT = getAgent('EventCatalog AI');
+// Someone's waiting on the assistant in the chat: it draws about three times as fast as an MCP agent
+const ASSISTANT_PACE = 0.3;
+
+/** What the assistant is told when it's opened on a canvas, after its usual instructions */
+const CANVAS_ASSISTANT_PROMPT = `
+The user is on an EventCatalog Studio canvas: a live, collaborative diagram. They opened you there to draw on it with them.
+When they ask you to diagram, design, map out, sketch or change something, draw it on the canvas with the canvas tools; don't answer with Mermaid or text diagrams.
+
+If you need to ask the user something first (what to diagram, or a request too vague to draw), ask straight away, without calling any tools.
+
+How to draw:
+1. Read the canvas before you change it (getCanvas), so you build on what's there and don't add what's already on it.
+2. Find what they asked about in the catalog (getResources, getResource, getMessagesProducedOrConsumedByResource, getArchitectureDiagramAsMermaid) and add those resources by collection and id. Catalog resources are connected to the related resources already on the canvas for you.
+   - A domain or system from the catalog: add it with contents: true, which brings everything in it at once. Don't look up and add its services and messages yourself.
+   - A service or message with what it connects to: add it with connections (e.g. ["sends", "receives"]), rather than finding each one.
+3. Only add new components (type, name, summary) for what isn't in the catalog yet, e.g. a proposed service or event when the user is designing something new.
+4. Add things in one or a few addToCanvas calls (with refs and edges), rather than one call per node. Use containers (domains, systems) when the diagram covers more than one of them.
+5. Don't lay the canvas out yourself: when you've finished, the canvas is tidied for you if you added things or connections. Only call layoutCanvas when the user asks you to tidy up.
+
+Explaining the diagram on the canvas:
+- Hotspots flag something people should know about a node, or a place on the canvas: a risk, a problem or something worth knowing (addHotspot: critical, warning or info, with a short title and why it matters). Use them when the user asks to flag, highlight or review things, e.g. single points of failure.
+- Sticky notes hold free text on the canvas: add a node with type "note" and its text in summary. Use them for notes, assumptions, open questions, suggestions and explanations. Keep each one very short and precise, like a sticky note on a whiteboard: one point in a few words (at most about 12), e.g. "Kafka: ordered, replayable order events". Add as many as are useful, one point per note, each beside the part of the diagram it's about: give it x/y about 300 to the right of, or 250 above, that node's centre (from getCanvas, after you've drawn), clear of other nodes. Add notes and text after the nodes they're about, so you know where those are. A note or text that would land on a node is moved to the nearest clear spot beside it, and notes stay beside their node when the canvas is tidied.
+- Text is words written straight on the canvas, without a note around them: add a node with type "text", what it says in summary, and fontSize for how big (22 by default; 40 to 60 for a title or a heading over part of the diagram). Use it for a diagram's title (above everything: y about 200 above the top of what's on the canvas), headings over areas (just above the domain or group they name), or short labels. Never put text where a node is. Move it with updateCanvasNode (x, y), and make it bigger or smaller with fontSize.
+- When asked to review or improve the design: flag each problem or risk with a hotspot on the node it's about, and write your suggestions on a few sticky notes (one per idea), then sum up what you found in a sentence or two. The hotspots you flag are listed under your reply for the user to go to, so don't list them again.
+Only add hotspots and notes when the user asks for them, or the request is about reviewing or annotating the design.
+
+Showing and explaining what's on the canvas:
+- showOnCanvas takes the user to nodes: their view zooms to them and they're highlighted. Use it to show them what you're talking about.
+- Whenever you mention something that's on the canvas in your reply, write it as a reference to it, which the user can hover or click to be taken there: [Order Service](#canvas-ref=service:<node id>). The type before the colon gives it its icon and colour: service, event, command, query, channel, domain, system, container (a data store), entity, agent, flow, user, team or data-product; for anything else, leave it out: [Customer](#canvas-ref=:<node id>). Use the node ids from getCanvas (or what addToCanvas created).
+- To walk the user through how something works (e.g. "walk me through how checkout works"), read the canvas, then call walkThrough with the steps in order: each a short title, a sentence or two on what happens, and the nodes involved (ids from getCanvas). The user sees the steps in the chat, and each takes them to its nodes on the canvas, starting with the first: don't write the steps out again in your reply, just a sentence to introduce them. If what they ask about isn't on the canvas, draw it first.
+
+Keep your reply short: say what you drew and anything you couldn't find in the catalog.
+`;
+
+/** The assistant's tools and instructions for the canvas it was opened on, or undefined if there's no such canvas */
+export const getCanvasAssistant = (canvasId: string) => {
+  const runtime = findStudioRuntime();
+  if (!runtime?.exists(canvasId)) return undefined;
+  const agent = () => agentOnCanvas(runtime, canvasId, ASSISTANT, { pace: ASSISTANT_PACE });
+  // Added things or connections since the canvas was last laid out: it's tidied once the assistant has finished
+  let drew = false;
+
+  const layout = async () => {
+    drew = false;
+    const { nodes, edges } = await runtime.withCanvas(canvasId, readCanvas);
+    // Notes and text stay beside what they're about
+    const positions = withNotesPlaced(nodes, await getLayoutPositions(nodes, edges));
+    await playLayout(agent().stage, positions);
+    return { laidOut: positions.nodes.size };
+  };
+
+  const tools = {
+    getCanvas: tool({
+      description:
+        'Reads everything on the canvas the user has open: its nodes (with ids, names, positions (their centres), sizes and the catalog resource they stand for), the connections between them, its hotspots and the comment threads. Read it before changing the canvas, and again to see what people have changed.',
+      inputSchema: z.object({}),
+      execute: async () => runtime.withCanvas(canvasId, describeCanvas),
+    }),
+    addToCanvas: tool({
+      description: `${ADD_TO_CANVAS_DESCRIPTION} The user watches you add them one by one. Use getResources to find catalog resources first, and prefer them over new components.`,
+      inputSchema: z.object({ nodes: nodeSpecsSchema, edges: edgeSpecsSchema.optional() }),
+      execute: async ({ nodes, edges }) => {
+        const { resources, relations } = await getCatalogResources();
+        const result = await playAddToCanvas(agent().stage, { nodes, edges }, indexCatalog(resources, relations));
+        // Notes and text alone (a review) leave the layout as it is
+        if (result.connections.length || nodes.some((node) => node.type !== 'note' && node.type !== 'text')) drew = true;
+        return result;
+      },
+    }),
+    updateCanvasNode: tool({
+      description:
+        'Renames, re-describes, re-versions or moves a node on the canvas (x/y: its new centre). Catalog resources keep their catalog name, summary and version. For notes and text, summary is what is written; fontSize makes text bigger or smaller.',
+      inputSchema: z.object({
+        nodeId: z.string(),
+        name: z.string().optional(),
+        summary: z.string().optional(),
+        version: z.string().optional().describe('e.g. 1.0.0'),
+        fontSize: z.number().min(8).max(200).optional().describe('For text: how big it is written, in pixels'),
+        x: z.number().optional(),
+        y: z.number().optional(),
+      }),
+      execute: async (update) => playUpdateNode(agent().stage, update),
+    }),
+    connectCanvasNodes: tool({
+      description:
+        'Draws connections between nodes already on the canvas, one at a time. Labels default to EventCatalog wording (e.g. "publishes event", "sent to").',
+      inputSchema: z.object({ edges: edgeSpecsSchema.min(1) }),
+      execute: async ({ edges }) => {
+        const result = await playConnectAll(agent().stage, edges);
+        if (result.connections.length) drew = true;
+        return result;
+      },
+    }),
+    addHotspot: tool({
+      description:
+        'Flags a hotspot on a node (nodeId), or at a place on the canvas (x, y): a marker everyone sees, with how serious it is, a short title and, optionally, why it matters and what to do about it. For risks, problems and things worth knowing, e.g. a single point of failure.',
+      inputSchema: z.object({
+        severity: z.enum(['critical', 'warning', 'info']).describe('critical: a problem; warning: a risk; info: worth knowing'),
+        title: z.string().describe('What people should know, in a few words, e.g. "Single point of failure"'),
+        description: z.string().optional().describe('Why it matters, and what to do about it'),
+        nodeId: z.string().optional().describe('The node it is about (from getCanvas or addToCanvas)'),
+        x: z.number().optional(),
+        y: z.number().optional(),
+      }),
+      execute: async (hotspot) => {
+        const { stage, author } = agent();
+        return playHotspot(stage, hotspot, author);
+      },
+    }),
+    showOnCanvas: tool({
+      description:
+        "Takes the user to nodes on the canvas: their view zooms to them and they're highlighted (only their view, not anyone else's). Use it to show them what you're talking about, e.g. the first step of a walkthrough.",
+      inputSchema: z.object({ nodeIds: z.array(z.string()).min(1).describe('The nodes to show (ids from getCanvas)') }),
+      execute: async ({ nodeIds }) => {
+        const onCanvas = await runtime.withCanvas(canvasId, (doc) => new Set(getCanvasMaps(doc).nodes.keys()));
+        const shown = nodeIds.filter((id) => onCanvas.has(id));
+        const missing = nodeIds.filter((id) => !onCanvas.has(id));
+        if (!shown.length)
+          return { error: `None of these are on the canvas: ${missing.join(', ')}. Use getCanvas for their ids.` };
+        return { nodeIds: shown, ...(missing.length && { notOnCanvas: missing }) };
+      },
+    }),
+    walkThrough: tool({
+      description:
+        'Walks the user through how something on the canvas works, step by step: they see the steps in the chat, and each takes them to its nodes on the canvas (starting with the first). Use it when they ask how something works or flows, e.g. "walk me through checkout".',
+      inputSchema: z.object({
+        title: z.string().describe('What it walks through, e.g. "How checkout works"'),
+        steps: z
+          .array(
+            z.object({
+              title: z.string().describe('The step, in a few words, e.g. "Customer places an order"'),
+              description: z.string().describe('What happens in this step, in a sentence or two'),
+              nodeIds: z.array(z.string()).min(1).describe('The nodes involved in this step (ids from getCanvas)'),
+            })
+          )
+          .min(1)
+          .max(20),
+      }),
+      execute: async ({ title, steps }) => {
+        const onCanvas = await runtime.withCanvas(canvasId, (doc) => new Set(getCanvasMaps(doc).nodes.keys()));
+        const missing = [...new Set(steps.flatMap((step) => step.nodeIds).filter((id) => !onCanvas.has(id)))];
+        return {
+          title,
+          steps: steps.map((step) => ({ ...step, nodeIds: step.nodeIds.filter((id) => onCanvas.has(id)) })),
+          ...(missing.length && { notOnCanvas: missing }),
+        };
+      },
+    }),
+    removeFromCanvas: tool({
+      description:
+        'Removes nodes (and their connections) or connections from the canvas. Only remove what the user asked for or what you added.',
+      inputSchema: z.object({ nodeIds: z.array(z.string()).optional(), connectionIds: z.array(z.string()).optional() }),
+      execute: async ({ nodeIds = [], connectionIds = [] }) => {
+        await playRemove(agent().stage, nodeIds, connectionIds);
+        return { removedNodes: nodeIds, removedConnections: connectionIds };
+      },
+    }),
+    layoutCanvas: tool({
+      description:
+        "Lays the whole canvas out again with EventCatalog's visualiser layout (left to right, connections routed around nodes). Only when the user asks you to tidy up: what you draw is laid out for you when you've finished.",
+      inputSchema: z.object({}),
+      execute: layout,
+    }),
+  };
+
+  return {
+    tools,
+    instructions: CANVAS_ASSISTANT_PROMPT,
+    /**
+     * The model started writing a call to a tool: a big addToCanvas takes a while to write, so the canvas shows the
+     * assistant planning it meanwhile
+     */
+    startedWriting: (toolName: string) => {
+      if (toolName !== 'addToCanvas') return;
+      const { stage } = agent();
+      stage.present({ pointer: stage.lastPointer ?? { x: 0, y: 0 }, selection: [], activity: 'Planning the diagram' });
+    },
+    /** The assistant has finished: what it drew is laid out, so the canvas is tidy (the model doesn't always remember to) */
+    finished: async () => {
+      if (drew) await layout();
+    },
+  };
+};

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

@@ -0,0 +1,27 @@
+import { reopeningIfEdited, type Author } from '@eventcatalog/visualiser/studio';
+import type { AgentStage } from '../agent-choreography';
+import type { AgentIdentity } from '../agents';
+import type { StudioRuntime } from './runtime';
+
+/**
+ * Work on a canvas as an agent: changes are played out like a person would make them (see agent-choreography),
+ * with the agent's pointer, selection and what it's doing shown to everyone on the canvas. Used by the MCP canvas
+ * tools and the assistant's.
+ */
+export const agentOnCanvas = (
+  runtime: StudioRuntime,
+  canvasId: string,
+  agent: AgentIdentity,
+  { pace }: Pick<AgentStage, 'pace'> = {}
+) => {
+  const author = { ...agent, agent: true } as Author;
+  const stage: AgentStage = {
+    // An agent changing an accepted (or rejected) canvas makes it a draft again, like a person doing it
+    change: (fn) => runtime.withCanvas(canvasId, (doc) => reopeningIfEdited(doc, author, () => fn(doc))),
+    present: (presence) => runtime.setAgentPresence(canvasId, agent, presence),
+    lastPointer: runtime.getAgentPointer(canvasId, agent),
+    sharesMoves: true,
+    pace,
+  };
+  return { stage, author };
+};