@eventcatalog/core 5.0.0-beta.11 → 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

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

package/eventcatalog/src/features/studio/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,10 +2,16 @@ 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 {
-  ADD_TO_CANVAS_DESCRIPTION,
+  replyToThread,
+  setThreadResolved,
+  type Author,
+  CANVAS_STATUSES,
+  setCanvasStatus,
   CATALOG_COLLECTIONS,
+} from '@eventcatalog/visualiser/studio';
+import {
+  ADD_TO_CANVAS_DESCRIPTION,
   describeCanvas,
   edgeSpecsSchema,
   nodeSpecsSchema,
@@ -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-follow-camera.ts

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