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

package/eventcatalog/src/components/Search/SearchDataLoader.astro

@@ -16,34 +16,22 @@
   import { setSidebarData, sidebarStore } from '@stores/sidebar-store';
   import { buildUrl } from '@utils/url-builder';
 
-  // Only fetch if we haven't already loaded the data
+  // Only fetch if we haven't already loaded the data. Fetched straight away rather than when
+  // the browser is idle: the sidebar's first paint comes from the server (see SideNav.astro),
+  // but drilling down and search wait on this data
   if (!sidebarStore.get()) {
-    const apiUrl = buildUrl('/api/sidebar-data.json', true);
-
-    const loadSidebarData = () => {
-      // Double-check cache in case another component loaded data while waiting for idle
-      if (sidebarStore.get()) return;
-
-      fetch(apiUrl)
-        .then((response) => {
-          if (!response.ok) {
-            throw new Error(`Failed to fetch sidebar data: ${response.status}`);
-          }
-          return response.json();
-        })
-        .then((data) => {
-          setSidebarData(data);
-        })
-        .catch((error) => {
-          console.error('Error loading sidebar data:', error);
-        });
-    };
-
-    // Defer non-critical sidebar payload fetch until browser is idle
-    if (typeof window.requestIdleCallback === 'function') {
-      window.requestIdleCallback(loadSidebarData, { timeout: 1200 });
-    } else {
-      setTimeout(loadSidebarData, 300);
-    }
+    fetch(buildUrl('/api/sidebar-data.json', true))
+      .then((response) => {
+        if (!response.ok) {
+          throw new Error(`Failed to fetch sidebar data: ${response.status}`);
+        }
+        return response.json();
+      })
+      .then((data) => {
+        setSidebarData(data);
+      })
+      .catch((error) => {
+        console.error('Error loading sidebar data:', error);
+      });
   }
 </script>

package/eventcatalog/src/components/SideNav/NestedSideBar/index.tsx

@@ -21,57 +21,56 @@ import {
   type FavoriteItem,
 } from '@stores/favorites-store';
 import {
+  buildNodeLookup,
   canCollapseGroup,
   findNodeKeyByUrl,
   getBadgeClasses,
   getDefaultCollapsedState,
   hidesDefaultItemIcon,
   isGroupCollapsed,
+  resolveNavRef,
+  rootLevel,
+  stripBasePath,
   toggleGroupCollapsed,
+  type NavigationLevel,
+  type SidebarSnapshot,
 } from './utils';
 import { resolveIconUrl } from '@utils/icon';
 
 const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
 
-/**
- * Strip the configured base path from a pathname so URL pattern matching works
- * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
- */
-const stripBasePath = (pathname: string): string => {
-  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
-  if (base && pathname.startsWith(base)) {
-    return pathname.slice(base.length) || '/';
-  }
-  return pathname;
-};
-
 // ============================================
 // Component
 // ============================================
 
-type NavigationLevel = {
-  key: string | null; // The key of the node that was drilled into (null for root)
-  entries: ChildRef[];
-  title: string;
-  badge?: string; // Category badge (e.g., "Domain", "Service")
+type NestedSideBarProps = {
+  /**
+   * This page's level, built on the server. It renders the sidebar into the HTML and keeps
+   * the island showing it until the full navigation data (sidebar-data.json) is loaded.
+   */
+  snapshot?: SidebarSnapshot;
 };
 
-export default function NestedSideBar() {
-  const data = useStore(sidebarStore);
+export default function NestedSideBar({ snapshot }: NestedSideBarProps) {
+  const storeData = useStore(sidebarStore);
   const favorites = useStore(favoritesStore);
+  // Drill-down, restoring state and favorites need the whole catalog; until it loads the
+  // snapshot only shows this page's level
+  const hasFullData = storeData !== null;
+  const data = storeData ?? snapshot?.data ?? null;
 
   // Guard against undefined data (e.g., during hydration)
   // Use useMemo to ensure stable references for roots and nodes
   const roots = useMemo(() => data?.roots ?? [], [data?.roots]);
   const nodes = useMemo(() => data?.nodes ?? {}, [data?.nodes]);
 
-  const [navigationStack, setNavigationStack] = useState<NavigationLevel[]>(() => [
-    { key: null, entries: [], title: 'Documentation' },
-  ]);
+  const [navigationStack, setNavigationStack] = useState<NavigationLevel[]>(
+    () => snapshot?.stack ?? [{ key: null, entries: [], title: 'Documentation' }]
+  );
   const [animationKey, setAnimationKey] = useState(0);
   const [slideDirection, setSlideDirection] = useState<'forward' | 'backward' | null>(null);
   const [isInitialized, setIsInitialized] = useState(false);
-  const [currentPath, setCurrentPath] = useState<string>('');
+  const [currentPath, setCurrentPath] = useState<string>(snapshot?.url ?? '');
   const [sectionCollapsePreferences, setSectionCollapsePreferences] = useState(loadCollapsedSections);
   const [showPathPreview, setShowPathPreview] = useState(false);
   const [showFullPath, setShowFullPath] = useState(false);
@@ -79,33 +78,7 @@ export default function NestedSideBar() {
 
   // Build a lookup map for faster URL navigation
   // Map format: "type:id" -> "nodeKey"
-  const nodeLookup = useMemo(() => {
-    const lookup = new Map<string, string>();
-
-    Object.entries(nodes).forEach(([key, value]) => {
-      // Skip keys that are references (string values pointing to other keys)
-      // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
-      if (typeof value === 'string') return;
-
-      // Key formats:
-      // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
-      // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
-      // - "list:name" (e.g., "list:domains") - skip these
-      const parts = key.split(':');
-
-      // Skip list items
-      if (parts[0] === 'list') return;
-
-      if (parts.length >= 2) {
-        // Store as "type:id"
-        const type = parts[0];
-        const id = parts[1];
-        lookup.set(`${type}:${id}`, key);
-      }
-    });
-
-    return lookup;
-  }, [nodes]);
+  const nodeLookup = useMemo(() => buildNodeLookup(nodes), [nodes]);
 
   /**
    * Toggle section collapse state
@@ -126,7 +99,7 @@ export default function NestedSideBar() {
       setNavigationStack((prevStack) => {
         // Only update if the current stack has no entries (initial state)
         if (prevStack.length === 1 && prevStack[0].entries.length === 0) {
-          return [{ key: null, entries: roots, title: 'Documentation' }];
+          return [rootLevel(roots)];
         }
         return prevStack;
       });
@@ -146,21 +119,7 @@ export default function NestedSideBar() {
    * Resolve a child reference to a NavNode
    * Handles both direct keys and string references (unversioned aliases pointing to versioned keys)
    */
-  const resolveRef = useCallback(
-    (ref: ChildRef): NavNode | null => {
-      if (typeof ref === 'string') {
-        const node = nodes[ref];
-        if (!node) return null;
-        // If node is a string, it's a reference to another key (e.g., unversioned alias)
-        if (typeof node === 'string') {
-          return (nodes[node] as NavNode) ?? null;
-        }
-        return node;
-      }
-      return ref;
-    },
-    [nodes]
-  );
+  const resolveRef = useCallback((ref: ChildRef): NavNode | null => resolveNavRef(nodes, ref), [nodes]);
 
   /**
    * Check if a node is visible (default: true)
@@ -175,7 +134,7 @@ export default function NestedSideBar() {
    */
   const buildStackFromPath = useCallback(
     (path: string[]): NavigationLevel[] => {
-      const stack: NavigationLevel[] = [{ key: null, entries: roots, title: 'Documentation' }];
+      const stack: NavigationLevel[] = [rootLevel(roots)];
 
       for (const key of path) {
         const node = resolveRef(key);
@@ -281,7 +240,7 @@ export default function NestedSideBar() {
           if (foundNode && foundNode.pages && foundNode.pages.length > 0) {
             // Fallback: Flattened navigation
             return [
-              { key: null, entries: roots, title: 'Documentation' },
+              rootLevel(roots),
               { key: foundNodeKey, entries: foundNode.pages, title: foundNode.title, badge: foundNode.badge },
             ];
           }
@@ -296,7 +255,7 @@ export default function NestedSideBar() {
             setSlideDirection('backward');
             setAnimationKey((prev) => prev + 1);
           }
-          return [{ key: null, entries: roots, title: 'Documentation' }];
+          return [rootLevel(roots)];
         });
         return true;
       }
@@ -309,14 +268,14 @@ export default function NestedSideBar() {
    * Restore state from localStorage on mount, or navigate to URL
    */
   useEffect(() => {
-    if (!data || roots.length === 0 || isInitialized) return;
+    if (!hasFullData || roots.length === 0 || isInitialized) return;
 
     const currentUrl = window.location.pathname;
     const normalizedCurrentUrl = stripBasePath(currentUrl);
 
     // Force root navigation on homepage
     if (normalizedCurrentUrl === '/' || normalizedCurrentUrl === '') {
-      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+      setNavigationStack([rootLevel(roots)]);
       setIsInitialized(true);
       return;
     }
@@ -347,7 +306,7 @@ export default function NestedSideBar() {
       const targetNode = resolveRef(targetKey);
       if (targetNode && targetNode.pages && targetNode.pages.length > 0) {
         finalStack = [
-          { key: null, entries: roots, title: 'Documentation' },
+          rootLevel(roots),
           { key: targetKey, entries: targetNode.pages, title: targetNode.title, badge: targetNode.badge },
         ];
       }
@@ -355,13 +314,13 @@ export default function NestedSideBar() {
 
     // 3. Fallback to root
     if (!finalStack) {
-      setNavigationStack([{ key: null, entries: roots, title: 'Documentation' }]);
+      setNavigationStack([rootLevel(roots)]);
     } else {
       setNavigationStack(finalStack);
     }
 
     setIsInitialized(true);
-  }, [data, roots, isInitialized, buildStackFromPath, findNodeKeyForUrl, tryConnectStack, resolveRef]);
+  }, [hasFullData, roots, isInitialized, buildStackFromPath, findNodeKeyForUrl, tryConnectStack, resolveRef]);
 
   /**
    * Save state whenever navigation changes
@@ -575,6 +534,7 @@ export default function NestedSideBar() {
    * Handle drilling down into an item with children
    */
   const handleDrillDown = (node: NavNode, nodeKey: string | null) => {
+    if (!hasFullData) return;
     if (node.pages && node.pages.length > 0) {
       setSlideDirection('forward');
       setAnimationKey((prev) => prev + 1);
@@ -590,7 +550,7 @@ export default function NestedSideBar() {
    * Navigate back one level
    */
   const navigateBack = () => {
-    if (navigationStack.length > 1) {
+    if (hasFullData && navigationStack.length > 1) {
       setSlideDirection('backward');
       setAnimationKey((prev) => prev + 1);
       setNavigationStack(navigationStack.slice(0, -1));
@@ -604,7 +564,7 @@ export default function NestedSideBar() {
    * Navigate to a specific level in the stack
    */
   const navigateToLevel = (levelIndex: number) => {
-    if (levelIndex < navigationStack.length - 1) {
+    if (hasFullData && levelIndex < navigationStack.length - 1) {
       setSlideDirection('backward');
       setAnimationKey((prev) => prev + 1);
       setNavigationStack(navigationStack.slice(0, levelIndex + 1));
@@ -634,6 +594,7 @@ export default function NestedSideBar() {
    * Navigate to a favorited item
    */
   const navigateToFavorite = (favorite: FavoriteItem) => {
+    if (!hasFullData) return;
     // If it has an href and no children, just navigate to the URL
     const node = resolveRef(favorite.nodeKey);
     if (favorite.href && (!node?.pages || node.pages.length === 0)) {

package/eventcatalog/src/components/SideNav/NestedSideBar/storage.ts

@@ -107,6 +107,8 @@ export const saveCollapsedSections = (preferences: SectionCollapsePreferences):
 };
 
 export const loadCollapsedSections = (): SectionCollapsePreferences => {
+  // Rendered on the server for the first paint, where there is nothing saved yet
+  if (typeof localStorage === 'undefined') return createSectionCollapsePreferences();
   try {
     const stored = localStorage.getItem(SECTION_PREFERENCES_KEY);
     if (stored) {

package/eventcatalog/src/components/SideNav/NestedSideBar/utils.ts

@@ -1,9 +1,130 @@
 // Shared utilities for NestedSideBar components
 
-import type { NavNode } from '@stores/sidebar-store/state';
+import type { ChildRef, NavigationData, NavNode } from '@stores/sidebar-store/state';
 
 export const SIDEBAR_GROUP_COLLAPSE_THRESHOLD = 5;
 
+/**
+ * Strip the configured base path from a pathname so URL pattern matching works
+ * regardless of the base path setting (e.g. `/eventcatalog/docs/...` → `/docs/...`).
+ */
+export const stripBasePath = (pathname: string): string => {
+  const base = __EC_BASE__.replace(/\/$/, ''); // e.g. '/eventcatalog'
+  if (base && pathname.startsWith(base)) {
+    return pathname.slice(base.length) || '/';
+  }
+  return pathname;
+};
+
+export type NavigationLevel = {
+  key: string | null; // The key of the node that was drilled into (null for root)
+  entries: ChildRef[];
+  title: string;
+  badge?: string; // Category badge (e.g., "Domain", "Service")
+};
+
+export const rootLevel = (roots: ChildRef[]): NavigationLevel => ({ key: null, entries: roots, title: 'Documentation' });
+
+/** Resolve a child reference to a node, following unversioned aliases (string → key). */
+export const resolveNavRef = (nodes: NavigationData['nodes'], ref: ChildRef): NavNode | null => {
+  if (typeof ref !== 'string') return ref;
+  const node = nodes[ref];
+  if (!node) return null;
+  if (typeof node === 'string') return (nodes[node] as NavNode) ?? null;
+  return node;
+};
+
+/** Map of "type:id" → versioned node key, used to match URLs to nodes. */
+export const buildNodeLookup = (nodes: NavigationData['nodes']): Map<string, string> => {
+  const lookup = new Map<string, string>();
+
+  Object.entries(nodes).forEach(([key, value]) => {
+    // Skip keys that are references (string values pointing to other keys)
+    // These are unversioned aliases like "domain:E-Commerce" -> "domain:E-Commerce:1.0.0"
+    if (typeof value === 'string') return;
+
+    // Key formats:
+    // - "type:id:version" (e.g., "service:OrdersService:0.0.3")
+    // - "type:id" (e.g., "user:john", "team:backend") - non-versioned resources
+    // - "list:name" (e.g., "list:domains") - skip these
+    const parts = key.split(':');
+
+    // Skip list items
+    if (parts[0] === 'list') return;
+
+    if (parts.length >= 2) {
+      // Store as "type:id"
+      lookup.set(`${parts[0]}:${parts[1]}`, key);
+    }
+  });
+
+  return lookup;
+};
+
+/**
+ * What the sidebar shows for a URL before it knows the reader's saved drill-down path:
+ * the root level on the homepage or for pages without children, otherwise the matching
+ * resource's own level (the same "flattened" stack the client falls back to).
+ */
+export const getStackForUrl = (
+  url: string,
+  data: NavigationData,
+  nodeLookup: ReadonlyMap<string, string> = buildNodeLookup(data.nodes)
+): NavigationLevel[] => {
+  const root = rootLevel(data.roots);
+  if (url === '/' || url === '') return [root];
+
+  const targetKey = findNodeKeyByUrl(url, data.nodes, nodeLookup);
+  const target = targetKey ? resolveNavRef(data.nodes, targetKey) : null;
+  if (!targetKey || !target?.pages?.length) return [root];
+
+  return [root, { key: targetKey, entries: target.pages, title: target.title, badge: target.badge }];
+};
+
+/**
+ * Everything the sidebar needs to render one page's level, without the whole catalog: the
+ * stack for the URL and only the nodes that level shows (its items, and the contents of its
+ * groups). Rendered on the server so the sidebar appears with the HTML, and handed to the
+ * island so it keeps showing it until the full navigation data loads.
+ */
+export type SidebarSnapshot = {
+  url: string;
+  stack: NavigationLevel[];
+  data: NavigationData;
+};
+
+const nodeLookupCache = new WeakMap<NavigationData, Map<string, string>>();
+
+export const buildSidebarSnapshot = (data: NavigationData, url: string): SidebarSnapshot => {
+  let nodeLookup = nodeLookupCache.get(data);
+  if (!nodeLookup) {
+    nodeLookup = buildNodeLookup(data.nodes);
+    nodeLookupCache.set(data, nodeLookup);
+  }
+
+  const stack = getStackForUrl(url, data, nodeLookup);
+  const level = stack[stack.length - 1];
+  const nodes: NavigationData['nodes'] = {};
+
+  const include = (ref: ChildRef) => {
+    if (typeof ref === 'string') {
+      if (ref in nodes) return;
+      const value = data.nodes[ref];
+      if (value === undefined) return;
+      nodes[ref] = value;
+      if (typeof value === 'string' && data.nodes[value] !== undefined) nodes[value] = data.nodes[value];
+    }
+    const node = resolveNavRef(data.nodes, ref);
+    // Groups render their children inline; items with children only need their own node
+    if (node?.type === 'group') node.pages?.forEach(include);
+  };
+
+  if (level.key) include(level.key);
+  level.entries.forEach(include);
+
+  return { url, stack, data: { roots: data.roots, nodes } };
+};
+
 /**
  * The user's overrides of each group's default collapse state, keyed by group id.
  * A group is in at most one set; absence means "use the group's default".

package/eventcatalog/src/components/SideNav/SideNav.astro

@@ -3,10 +3,18 @@ import type { HTMLAttributes } from 'astro/types';
 
 interface Props extends Omit<HTMLAttributes<'div'>, 'children'> {}
 import NestedSideBar from './NestedSideBar';
+import { buildSidebarSnapshot, stripBasePath } from './NestedSideBar/utils';
+import { getNestedSideBarData } from '@stores/sidebar-store/state';
 import { ClientRouter } from 'astro:transitions';
+
+// Render this page's sidebar level into the HTML so it shows before any JavaScript runs;
+// the full navigation still loads from /api/sidebar-data.json (see SearchDataLoader)
+const snapshot = buildSidebarSnapshot(await getNestedSideBarData(), stripBasePath(Astro.url.pathname));
 ---
 
 <div {...Astro.props}>
   <ClientRouter />
-  <NestedSideBar client:only="react" />
+  <NestedSideBar client:only="react" snapshot={snapshot}>
+    <NestedSideBar slot="fallback" snapshot={snapshot} />
+  </NestedSideBar>
 </div>

package/eventcatalog/src/features/mcp/apps/canvas/shared.ts

@@ -1,6 +1,6 @@
 // Shared by the canvas MCP App (client) and the MCP server: no server-only imports here
 import type { CatalogRelation, CatalogResource } from '../../../studio/catalog-resources';
-import type { CanvasStatus } from '../../../studio/canvas-doc';
+import { type CanvasStatus } from '@eventcatalog/visualiser/studio';
 
 export const CANVAS_RESOURCE_URI = 'ui://eventcatalog/canvas.html';
 /** Key of the payload in openCanvas results' `_meta` */
@@ -40,8 +40,8 @@ export type CanvasView = {
   canvasUrl: string;
   /** The EventCatalog MCP server, for "Connect your agent" */
   mcpUrl: string;
-  /** What to call the user on the canvas, when the agent knows their name */
-  userName?: string;
+  /** The chat's agent: the view joins the canvas as it (its name, colour and logo) */
+  agent?: { name: string; color: string };
 };
 
 export type CanvasCatalog = { resources: CatalogResource[]; relations: CatalogRelation[] };

package/eventcatalog/src/features/mcp/apps/canvas/styles.css

@@ -4,10 +4,12 @@
  */
 @import 'tailwindcss' source(none);
 @import '../../../../styles/theme.css';
-@import '../../../studio/studio.css';
+@import '@eventcatalog/visualiser/studio.css';
 
 @source './*.tsx';
 @source '../../../studio/components/*.{ts,tsx}';
+/* Studio's shared canvas (nodes, comments, hotspots), from the visualiser in this repo */
+@source '../../../../../../../visualiser/src/studio';
 
 body {
   margin: 0;

package/eventcatalog/src/features/mcp/apps/canvas/view.tsx

@@ -15,7 +15,8 @@ import type { App } from '@modelcontextprotocol/ext-apps';
 import styles from './styles.css?inline';
 import visualiserStyles from '@eventcatalog/visualiser/styles.css?inline';
 import StudioDesigner, { type SelectedNode } from '@features/studio/components/StudioDesigner';
-import { CANVAS_STATUS_LOOK, STATUS } from '@features/studio/components/status';
+import { getAgent } from '@features/studio/agents';
+import { CANVAS_STATUS_LOOK, STATUS } from '@eventcatalog/visualiser/studio';
 import { getToolResultPayload, mountView, useMcpAppView } from '../shared/app-view';
 import {
   CANVAS_CATALOG_TOOL,
@@ -212,10 +213,10 @@ function CanvasApp() {
   const iconButton =
     'flex items-center gap-1 rounded-md px-2 py-1 text-xs text-[rgb(var(--ec-page-text-muted))] hover:bg-[rgb(var(--ec-page-border)/0.5)]';
 
-  // No join form inside a chat: use the name the agent passed, or name them after the chat they're in
+  // No join form inside a chat: it joins as the chat's agent (e.g. ChatGPT or Claude, with its logo), as the agent
+  // working on the canvas does, else as the chat it's in
   const hostName = app?.getHostVersion()?.name;
-  const userName = (view: CanvasView) =>
-    view.userName ?? `${hostName ? hostName.replace(/^\w/, (letter) => letter.toUpperCase()) : 'Chat'} user`;
+  const agentOf = (view: CanvasView) => view.agent ?? getAgent(undefined, hostName);
 
   return (
     <div className="flex flex-col" style={{ height: fullscreen ? '100vh' : INLINE_HEIGHT }}>
@@ -255,11 +256,12 @@ function CanvasApp() {
             shareUrl={canvas.canvasUrl}
             mcpUrl={canvas.mcpUrl}
             syncViaTools={syncViaTools}
-            defaultName={userName(canvas)}
+            asAgent={agentOf(canvas)}
             resources={catalog.resources}
             relations={catalog.relations}
             onSelectionChange={setSelection}
             followChanges
+            paletteCollapsed
           />
         ) : (
           <CanvasPicker