@eventcatalog/core 4.9.0 → 4.10.1

package/eventcatalog/src/components/MDX/ArchitectureGraph/AstroArchitectureGraph.tsx

@@ -0,0 +1,42 @@
+import { useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
+import CatalogForceGraph from '@components/CatalogGraph/CatalogForceGraph';
+import type { CatalogGraphWireLink, CatalogGraphWireNode } from '@utils/node-graphs/catalog-force-graph';
+
+interface Props {
+  /** DOM id of the placeholder div ArchitectureGraphPortal rendered into the MDX content */
+  portalId: string;
+  nodes: CatalogGraphWireNode[];
+  links: CatalogGraphWireLink[];
+  linkLabels: string[];
+  initialLens?: string;
+  initialFocus?: string;
+  initialFocusDepth?: number;
+  showSearch?: boolean;
+  showLegend?: boolean;
+  showLensPicker?: boolean;
+  /** Base URL of the standalone /visualiser/graph page — the graph renders an
+   * "open full screen" link carrying its live view state (focus, depth, lens) */
+  href?: string;
+  hrefLabel?: string;
+}
+
+// The island mounts outside the MDX content, finds the placeholder div the MDX
+// component map emitted, and portals the graph into it — same pattern as the
+// visualiser's NodeGraph.
+const AstroArchitectureGraph = ({ portalId, href, hrefLabel, ...graphProps }: Props) => {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+
+  useEffect(() => {
+    setContainer(document.getElementById(portalId));
+  }, [portalId]);
+
+  if (!container) return null;
+
+  return createPortal(
+    <CatalogForceGraph {...graphProps} syncUrl={false} zoomOnScroll={false} openInGraphUrl={href} openInGraphLabel={hrefLabel} />,
+    container
+  );
+};
+
+export default AstroArchitectureGraph;

package/eventcatalog/src/components/MDX/Design/Design.astro

@@ -4,6 +4,8 @@ import fs from 'fs';
 import { getAbsoluteFilePathForAstroFile } from '@utils/files';
 import Admonition from '@components/MDX/Admonition';
 import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 
 import { isVisualiserEnabled, isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
 import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';

package/eventcatalog/src/components/MDX/EntityMap/EntityMap.astro

@@ -3,6 +3,8 @@ import { getDomains } from '@utils/collections/domains';
 import { getNodesAndEdges } from '@utils/node-graphs/domain-entity-map.ts';
 import Admonition from '@components/MDX/Admonition';
 import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import { getVersionFromCollection } from '@utils/collections/versions';
 import { getServices } from '@utils/collections/services';
 import { isEventCatalogChatEnabled, isDevMode } from '@utils/feature';

package/eventcatalog/src/components/MDX/Flow/Flow.astro

@@ -3,6 +3,8 @@ import { getFlows } from '@utils/collections/flows';
 import { getNodesAndEdges } from '@utils/node-graphs/flows-node-graph';
 import Admonition from '@components/MDX/Admonition';
 import AstroNodeGraph from '../NodeGraph/AstroNodeGraph';
+// Visualiser styles ship in the page head so ClientRouter navigations keep them (see NodeGraph.astro).
+import '@eventcatalog/visualiser/styles-core.css';
 import { getVersionFromCollection } from '@utils/collections/versions';
 import { isVisualiserEnabled, isEventCatalogChatEnabled, isDevMode } from '@utils/feature';
 import { loadSavedLayout, applyLayoutToNodes, buildResourceKey } from '@utils/node-graphs/layout-persistence';

package/eventcatalog/src/components/MDX/NodeGraph/AstroNodeGraph.tsx

@@ -6,9 +6,13 @@
  * - Navigation using Astro's navigate function
  * - Layout persistence via Astro API routes
  * - URL building with Astro's URL utilities
+ *
+ * Note: the visualiser stylesheet is deliberately NOT imported here. Every Astro file that
+ * renders this component imports `@eventcatalog/visualiser/styles-core.css` itself so the
+ * CSS ships in the page head and survives ClientRouter navigations (see NodeGraph.astro).
  */
 
-import { useCallback, lazy, Suspense, useEffect } from 'react';
+import { useCallback, lazy, Suspense } from 'react';
 import type { Node, Edge } from '@xyflow/react';
 import { buildUrl } from '@utils/url-builder';
 
@@ -42,12 +46,6 @@ interface AstroNodeGraphProps {
 }
 
 const AstroNodeGraph = ({ isDevMode = false, resourceKey, ...otherProps }: AstroNodeGraphProps) => {
-  useEffect(() => {
-    // Load visualizer styles only when this component is mounted.
-    // Use the core-scoped stylesheet so visualizer styles don't override EventCatalog utility classes globally.
-    import('@eventcatalog/visualiser/styles-core.css');
-  }, []);
-
   // Astro-specific navigation handler
   const handleNavigate = useCallback((url: string) => {
     // Use window.location for navigation since we can't import astro:transitions/client in a React component

package/eventcatalog/src/components/MDX/NodeGraph/NodeGraph.astro

@@ -1,5 +1,10 @@
 ---
 import AstroNodeGraph from './AstroNodeGraph';
+// Imported here (server side) rather than from the React island: Astro then emits it as a
+// <link> in the page head, which survives ClientRouter navigations. A dynamic import from the
+// island injects a <style> that the view-transition head swap removes — and the cached module
+// never re-injects it, leaving the graph unstyled until a full reload.
+import '@eventcatalog/visualiser/styles-core.css';
 import { getNodesAndEdges as getNodesAndEdgesForAgent } from '@utils/node-graphs/agents-node-graph';
 import { getNodesAndEdges as getNodesAndEdgesForService } from '@utils/node-graphs/services-node-graph';
 import {

package/eventcatalog/src/components/MDX/components.tsx

@@ -35,6 +35,7 @@ import MermaidFileLoader from '@components/MDX/MermaidFileLoader/MermaidFileLoad
 import LikeC4View from '@components/MDX/LikeC4View/LikeC4View.astro';
 //  Portals: required for server/client components
 import NodeGraphPortal from '@components/MDX/NodeGraph/NodeGraphPortal';
+import ArchitectureGraphPortal from '@components/MDX/ArchitectureGraph/ArchitectureGraphPortal';
 import ContextDiagramPortal from '@components/MDX/ContextDiagram/ContextDiagramPortal';
 import SystemContextMapPortal from '@components/MDX/SystemContextMap/SystemContextMapPortal';
 import SchemaViewerPortal from '@components/MDX/SchemaViewer/SchemaViewerPortal';
@@ -50,6 +51,10 @@ const getEntityMapCollection = (props: any, mdxProp: any) => {
 };
 
 const components = (props: any) => {
+  // Occurrence counter so multiple <ArchitectureGraph/> tags on one page each get
+  // their own portal — MDX renders in document order, matching the body scan order
+  // the host pages use to render the islands.
+  let architectureGraphOccurrence = 0;
   return {
     Attachments: (mdxProp: any) => jsx(Attachments, { ...props, ...mdxProp }),
     CustomProperties: (mdxProp: any) => jsx(CustomProperties, { ...props, ...mdxProp }),
@@ -69,6 +74,14 @@ const components = (props: any) => {
     ADRTable: (mdxProp: any) => jsx(ADRTable, { ...props, ...mdxProp }),
     EntityPropertiesTable: (mdxProp: any) => jsx(EntityPropertiesTable, { ...props, ...mdxProp }),
     NodeGraph: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
+    ArchitectureGraph: (mdxProp: any) =>
+      jsx(ArchitectureGraphPortal, {
+        ...props.data,
+        ...mdxProp,
+        occurrenceIndex: architectureGraphOccurrence++,
+        props,
+        mdxProp,
+      }),
     ComponentDiagram: (mdxProp: any) => jsx(NodeGraphPortal, { ...props.data, ...mdxProp, props, mdxProp }),
     ContextDiagram: (mdxProp: any) => jsx(ContextDiagramPortal, { ...props.data, ...mdxProp, props, mdxProp }),
     SystemContextMap: (mdxProp: any) => jsx(SystemContextMapPortal, { ...mdxProp }),

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

@@ -1,10 +1,17 @@
 'use client';
 
-import { useState, useEffect, useCallback, useMemo } from 'react';
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react';
 import * as LucideIcons from 'lucide-react';
 import { ChevronRight, ChevronLeft, ChevronDown, Home, Star } from 'lucide-react';
 import type { NavNode, ChildRef } from '@stores/sidebar-store/state';
-import { saveState, loadState, saveCollapsedSections, loadCollapsedSections } from './storage';
+import {
+  saveState,
+  loadState,
+  saveCollapsedSections,
+  loadCollapsedSections,
+  saveScrollPosition,
+  loadScrollPosition,
+} from './storage';
 import { useStore } from '@nanostores/react';
 import { sidebarStore } from '@stores/sidebar-store';
 import {
@@ -13,7 +20,14 @@ import {
   removeFavorite as removeFavoriteAction,
   type FavoriteItem,
 } from '@stores/favorites-store';
-import { canCollapseGroup, findNodeKeyByUrl, getBadgeClasses, getGroupLabel, isGroupCollapsed } from './utils';
+import {
+  canCollapseGroup,
+  findNodeKeyByUrl,
+  getBadgeClasses,
+  getDefaultCollapsedState,
+  isGroupCollapsed,
+  toggleGroupCollapsed,
+} from './utils';
 import { resolveIconUrl } from '@utils/icon';
 
 const cn = (...classes: (string | false | undefined)[]) => classes.filter(Boolean).join(' ');
@@ -60,6 +74,7 @@ export default function NestedSideBar() {
   const [sectionCollapsePreferences, setSectionCollapsePreferences] = useState(loadCollapsedSections);
   const [showPathPreview, setShowPathPreview] = useState(false);
   const [showFullPath, setShowFullPath] = useState(false);
+  const navRef = useRef<HTMLElement | null>(null);
 
   // Build a lookup map for faster URL navigation
   // Map format: "type:id" -> "nodeKey"
@@ -94,19 +109,9 @@ export default function NestedSideBar() {
   /**
    * Toggle section collapse state
    */
-  const toggleSectionCollapse = (sectionId: string) => {
+  const toggleSectionCollapse = (sectionId: string, defaultCollapsed = true) => {
     setSectionCollapsePreferences((previousPreferences) => {
-      const nextPreferences = {
-        expanded: new Set(previousPreferences.expanded),
-      };
-      const isCurrentlyCollapsed = isGroupCollapsed(true, sectionId, previousPreferences);
-
-      if (isCurrentlyCollapsed) {
-        nextPreferences.expanded.add(sectionId);
-      } else {
-        nextPreferences.expanded.delete(sectionId);
-      }
-
+      const nextPreferences = toggleGroupCollapsed(sectionId, previousPreferences, defaultCollapsed);
       saveCollapsedSections(nextPreferences);
       return nextPreferences;
     });
@@ -416,6 +421,50 @@ export default function NestedSideBar() {
     };
   }, [isInitialized, findAndNavigateToUrl, currentPath]);
 
+  /**
+   * Keep the selected item visible. On a full page load the nav remounts scrolled to the
+   * top, so first restore the offset saved for this drill-down path, then nudge the
+   * active item into view if it still isn't. `block: 'nearest'` never scrolls when the
+   * item is already visible, so clicking around near the top doesn't jump.
+   */
+  useEffect(() => {
+    if (!isInitialized) return;
+    const nav = navRef.current;
+    if (!nav) return;
+
+    const pathKey = getCurrentPath().join('/') || 'root';
+    const savedScrollTop = loadScrollPosition(pathKey);
+    if (savedScrollTop !== null) nav.scrollTop = savedScrollTop;
+
+    const active = nav.querySelector<HTMLElement>('[data-active="true"]');
+    if (!active) return;
+
+    const navRect = nav.getBoundingClientRect();
+    const activeRect = active.getBoundingClientRect();
+    const isVisible = activeRect.top >= navRect.top && activeRect.bottom <= navRect.bottom;
+    if (!isVisible) active.scrollIntoView({ block: 'nearest' });
+  }, [isInitialized, currentPath, navigationStack, getCurrentPath]);
+
+  /**
+   * Persist the nav scroll offset as it changes.
+   */
+  useEffect(() => {
+    if (!isInitialized) return;
+    const nav = navRef.current;
+    if (!nav) return;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const onScroll = () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => saveScrollPosition(getCurrentPath().join('/') || 'root', nav.scrollTop), 150);
+    };
+    nav.addEventListener('scroll', onScroll, { passive: true });
+    return () => {
+      clearTimeout(timer);
+      nav.removeEventListener('scroll', onScroll);
+    };
+  }, [isInitialized, navigationStack, getCurrentPath]);
+
   /**
    * Check if a node is favorited
    * Note: This hook must be defined before any early returns to comply with Rules of Hooks
@@ -658,14 +707,15 @@ export default function NestedSideBar() {
   };
 
   /**
-   * Render a group with its children
+   * Render a group with its children.
+   *
+   * Groups render as a docs-style tree: every group has its caret on the right; top-level
+   * sections also carry an icon tile. Each level's children hang off a vertical guide.
    */
-  const renderGroup = (group: NavNode, groupKey: string | null, index: number) => {
-    // Get optional icon for group
+  const renderGroup = (group: NavNode, groupKey: string | null, index: number, depth = 0) => {
     const GroupIcon = group.icon ? (LucideIcons as unknown as Record<string, LucideIcons.LucideIcon>)[group.icon] : null;
-    const isSubtleGroup = group.subtle === true;
+    const isNested = depth > 0;
 
-    // Get visible children
     const visibleChildren =
       group.pages?.filter((childRef) => {
         const child = resolveRef(childRef);
@@ -673,46 +723,36 @@ export default function NestedSideBar() {
       }) ?? [];
 
     const groupId = groupKey || group.collapseKey || `${currentLevel.key ?? 'root'}:group:${group.title}`;
-    const canCollapse = canCollapseGroup(visibleChildren.length, isTopLevel, group.collapsible);
-    const isCollapsed = isGroupCollapsed(canCollapse, groupId, sectionCollapsePreferences);
-
-    // When a group's children are subtle subgroups (e.g. Resources > Services/Flows/Data Stores),
-    // they render flush under the parent icon instead of inside the indented border guide.
-    const hasSubtleChildren = visibleChildren.some((childRef) => {
-      const child = resolveRef(childRef);
-      return child && isGroup(child) && child.subtle === true;
-    });
-
-    const headerContent = (
+    const canCollapse = canCollapseGroup(isTopLevel, group.collapsible, group.collapsed);
+    const defaultCollapsed = getDefaultCollapsedState(visibleChildren.length, group.collapsed);
+    const isCollapsed = isGroupCollapsed(canCollapse, groupId, sectionCollapsePreferences, defaultCollapsed);
+    const header = isNested ? (
       <>
-        <div className="flex items-center gap-2">
-          {GroupIcon && (
-            <span
-              className={cn(
-                'flex items-center justify-center w-5 h-5 rounded',
-                isSubtleGroup
-                  ? 'bg-[rgb(var(--ec-content-hover))] text-[rgb(var(--ec-content-text-muted))]'
-                  : 'bg-[rgb(var(--ec-group-icon-bg))] text-[rgb(var(--ec-group-icon-text))]'
-              )}
-            >
-              <GroupIcon className="w-3 h-3" />
-            </span>
-          )}
-          <span
+        {GroupIcon && <GroupIcon className="w-3.5 h-3.5 flex-shrink-0 text-[rgb(var(--ec-content-text-muted))]" />}
+        <span className="text-[12px] font-medium text-[rgb(var(--ec-content-text))] truncate">{group.title}</span>
+        {canCollapse && (
+          <ChevronDown
             className={cn(
-              isSubtleGroup
-                ? 'text-[9px] font-semibold uppercase tracking-[0.1em] text-[rgb(var(--ec-content-text-muted))]'
-                : 'text-[12px] font-semibold tracking-tight text-[rgb(var(--ec-content-text))]'
+              'ml-auto w-3.5 h-3.5 flex-shrink-0 text-[rgb(var(--ec-icon-color))] transition-transform',
+              isCollapsed && '-rotate-90'
             )}
-          >
-            {getGroupLabel(group.title, visibleChildren.length)}
+          />
+        )}
+      </>
+    ) : (
+      <>
+        {GroupIcon && (
+          <span className="flex items-center justify-center w-5 h-5 flex-shrink-0 rounded bg-[rgb(var(--ec-group-icon-bg))] text-[rgb(var(--ec-group-icon-text))]">
+            <GroupIcon className="w-3 h-3" />
           </span>
-        </div>
+        )}
+        <span className="text-[12px] font-semibold tracking-tight text-[rgb(var(--ec-content-text))] truncate">
+          {group.title}
+        </span>
         {canCollapse && (
           <ChevronDown
             className={cn(
-              isSubtleGroup ? 'w-3.5 h-3.5' : 'w-4 h-4',
-              'text-[rgb(var(--ec-icon-color))] transition-transform',
+              'ml-auto w-4 h-4 flex-shrink-0 text-[rgb(var(--ec-icon-color))] transition-transform',
               isCollapsed && '-rotate-90'
             )}
           />
@@ -720,32 +760,30 @@ export default function NestedSideBar() {
       </>
     );
 
+    const headerClasses = cn(
+      'group flex items-center w-full rounded-md text-left transition-colors',
+      isNested ? 'gap-1.5 px-2 py-1.5' : 'gap-2 px-2 py-1.5',
+      canCollapse && 'cursor-pointer hover:bg-[rgb(var(--ec-content-hover))]'
+    );
+
+    // Top level: the guide line sits under the centre of the icon tile (8px padding + half of
+    // 20px). Nested: carets sit on the right, so the guide is simply inset from the label.
+    const childrenClasses = cn(
+      'flex flex-col gap-px mt-0.5 border-l border-[rgb(var(--ec-content-border))]',
+      isNested ? 'ml-3 pl-1.5' : 'ml-[18px] pl-2'
+    );
+
     return (
-      <div key={`group-${groupKey || index}`} className={cn(isSubtleGroup ? 'mb-2 last:mb-1' : 'mb-5 last:mb-2')}>
+      <div key={`group-${groupKey || index}`} className={cn(isNested ? 'mt-0.5' : 'mb-4 last:mb-1')}>
         {canCollapse ? (
-          <button
-            onClick={() => toggleSectionCollapse(groupId)}
-            className={cn(
-              'flex items-center justify-between w-full rounded-md transition-colors cursor-pointer',
-              isSubtleGroup
-                ? 'px-2 py-1 hover:bg-[rgb(var(--ec-content-hover))]/60'
-                : 'px-2 py-1.5 hover:bg-[rgb(var(--ec-content-hover))]'
-            )}
-          >
-            {headerContent}
+          <button type="button" onClick={() => toggleSectionCollapse(groupId, defaultCollapsed)} className={headerClasses}>
+            {header}
           </button>
         ) : (
-          <div className={cn('flex items-center justify-between', isSubtleGroup ? 'px-2 py-1' : 'px-2 py-1.5')}>
-            {headerContent}
-          </div>
+          <div className={headerClasses}>{header}</div>
         )}
         {!isCollapsed && (
-          <div
-            className={cn(
-              'flex flex-col gap-0.5 border-[rgb(var(--ec-content-border))]',
-              isSubtleGroup ? 'border-l ml-4 mt-1' : hasSubtleChildren ? 'mt-1' : 'border-l ml-4 mt-1'
-            )}
-          >
+          <div className={childrenClasses}>
             {visibleChildren.map((childRef, childIndex) => {
               const child = resolveRef(childRef);
               if (!child) return null;
@@ -753,22 +791,13 @@ export default function NestedSideBar() {
               const childKey = typeof childRef === 'string' ? childRef : null;
 
               if (isGroup(child)) {
-                // Skip nested groups with no visible children
                 if (!hasVisibleChildren(child)) return null;
-
-                return (
-                  <div
-                    key={`nested-group-${childKey || childIndex}`}
-                    className={cn(child.subtle ? 'mt-1' : 'ml-3 mt-1.5 pl-3 border-l border-[rgb(var(--ec-content-border))]')}
-                  >
-                    {renderGroup(child, childKey, childIndex)}
-                  </div>
-                );
+                return renderGroup(child, childKey, childIndex, depth + 1);
               }
-              // Inside a subtle subgroup (e.g. a domain's Resources > Services list) the
-              // section header already conveys the resource type, so suppress the default
-              // per-item icon and only keep a custom icon if one is defined.
-              return renderItem(child, childKey, childIndex, isSubtleGroup);
+
+              // Under a nested group the header already conveys the resource type, so the
+              // default per-collection glyph is dropped; custom icons still show.
+              return renderItem(child, childKey, childIndex, isNested);
             })}
           </div>
         )}
@@ -845,7 +874,7 @@ export default function NestedSideBar() {
     );
 
     const baseClasses =
-      'group flex items-center justify-between w-full px-3 py-1.5 border border-transparent cursor-pointer text-left transition-colors hover:bg-[rgb(var(--ec-content-hover))] active:bg-[rgb(var(--ec-content-hover))]';
+      'group flex items-center justify-between w-full px-2 py-1.5 rounded-md cursor-pointer text-left transition-colors hover:bg-[rgb(var(--ec-content-hover))] active:bg-[rgb(var(--ec-content-hover))]';
     const parentClasses = itemHasChildren ? 'font-medium' : '';
     const activeClasses = isActive ? 'bg-[rgb(var(--ec-rail-active-bg))] hover:bg-[rgb(var(--ec-rail-active-bg))]' : '';
 
@@ -857,6 +886,8 @@ export default function NestedSideBar() {
           href={item.href}
           title={item.title}
           target={item.external ? '_blank' : undefined}
+          aria-current={isActive ? 'page' : undefined}
+          data-active={isActive ? 'true' : undefined}
           className={cn(baseClasses, parentClasses, activeClasses)}
         >
           {content}
@@ -870,6 +901,7 @@ export default function NestedSideBar() {
         key={`item-${itemKey || index}`}
         title={item.title}
         onClick={() => handleDrillDown(item, itemKey)}
+        data-active={isActive ? 'true' : undefined}
         className={cn(baseClasses, parentClasses, activeClasses)}
       >
         {content}
@@ -1040,6 +1072,7 @@ export default function NestedSideBar() {
       {/* Navigation Content */}
       <nav
         key={animationKey}
+        ref={navRef}
         className={cn('min-h-0 flex-1 overflow-y-auto overflow-x-hidden p-4 px-2', getAnimationClass())}
         style={{
           scrollbarWidth: 'thin',

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

@@ -1,4 +1,4 @@
-import type { SectionCollapsePreferences } from './utils';
+import { createSectionCollapsePreferences, type SectionCollapsePreferences } from './utils';
 
 // ============================================
 // Local Storage Persistence
@@ -7,6 +7,7 @@ import type { SectionCollapsePreferences } from './utils';
 const STORAGE_KEY = 'eventcatalog-sidebar-nav';
 const SECTION_PREFERENCES_KEY = 'eventcatalog-sidebar-sections:v2';
 const FAVORITES_KEY = 'eventcatalog-sidebar-favorites';
+const SCROLL_KEY = 'eventcatalog-sidebar-scroll';
 
 // ============================================
 // Types
@@ -47,13 +48,59 @@ export const loadState = (): PersistedState | null => {
   }
 };
 
+// ============================================
+// Scroll position
+// ============================================
+
+/**
+ * The sidebar remounts on every full page load, which resets its scroll offset to the
+ * top. Persist offsets (per tab) so the list looks stationary when you follow a link near
+ * the bottom. A capped map keyed by drill-down path, so scrolling one level doesn't lose
+ * another level's offset (root -> drill in -> scroll -> back keeps the root position).
+ */
+const MAX_SCROLL_ENTRIES = 30;
+
+export const saveScrollPosition = (pathKey: string, scrollTop: number): void => {
+  try {
+    const stored = sessionStorage.getItem(SCROLL_KEY);
+    const parsed = stored ? JSON.parse(stored) : {};
+    const offsets: Record<string, number> = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    // Re-insert so the map stays ordered by recency, then drop the oldest beyond the cap.
+    delete offsets[pathKey];
+    offsets[pathKey] = scrollTop;
+    const keys = Object.keys(offsets);
+    for (const stale of keys.slice(0, Math.max(0, keys.length - MAX_SCROLL_ENTRIES))) {
+      delete offsets[stale];
+    }
+    sessionStorage.setItem(SCROLL_KEY, JSON.stringify(offsets));
+  } catch (e) {
+    console.warn('Failed to save sidebar scroll position:', e);
+  }
+};
+
+export const loadScrollPosition = (pathKey: string): number | null => {
+  try {
+    const stored = sessionStorage.getItem(SCROLL_KEY);
+    if (!stored) return null;
+    const offsets = JSON.parse(stored);
+    const scrollTop = offsets && typeof offsets === 'object' ? offsets[pathKey] : undefined;
+    return typeof scrollTop === 'number' ? scrollTop : null;
+  } catch (e) {
+    console.warn('Failed to load sidebar scroll position:', e);
+    return null;
+  }
+};
+
 // ============================================
 // Collapsed Sections
 // ============================================
 
 export const saveCollapsedSections = (preferences: SectionCollapsePreferences): void => {
   try {
-    localStorage.setItem(SECTION_PREFERENCES_KEY, JSON.stringify({ expanded: [...preferences.expanded] }));
+    localStorage.setItem(
+      SECTION_PREFERENCES_KEY,
+      JSON.stringify({ expanded: [...preferences.expanded], collapsed: [...preferences.collapsed] })
+    );
   } catch (e) {
     console.warn('Failed to save collapsed sections:', e);
   }
@@ -64,15 +111,16 @@ export const loadCollapsedSections = (): SectionCollapsePreferences => {
     const stored = localStorage.getItem(SECTION_PREFERENCES_KEY);
     if (stored) {
       const preferences = JSON.parse(stored);
-      return {
-        expanded: new Set(Array.isArray(preferences.expanded) ? preferences.expanded : []),
-      };
+      return createSectionCollapsePreferences(
+        Array.isArray(preferences.expanded) ? preferences.expanded : [],
+        Array.isArray(preferences.collapsed) ? preferences.collapsed : []
+      );
     }
 
-    return { expanded: new Set() };
+    return createSectionCollapsePreferences();
   } catch (e) {
     console.warn('Failed to load collapsed sections:', e);
-    return { expanded: new Set() };
+    return createSectionCollapsePreferences();
   }
 };
 

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

@@ -1,30 +1,40 @@
 import { describe, expect, it } from 'vitest';
-import { canCollapseGroup, findNodeKeyByUrl, getGroupLabel, isGroupCollapsed } from './utils';
+import {
+  canCollapseGroup,
+  createSectionCollapsePreferences,
+  findNodeKeyByUrl,
+  getDefaultCollapsedState,
+  isGroupCollapsed,
+  toggleGroupCollapsed,
+} from './utils';
 
-const preferences = (expanded: string[] = []) => ({
-  expanded: new Set(expanded),
-});
+const preferences = (expanded: string[] = [], collapsed: string[] = []) => createSectionCollapsePreferences(expanded, collapsed);
 
 describe('sidebar group presentation', () => {
-  it('includes the visible child count in the group label', () => {
-    expect(getGroupLabel('Outbound Messages', 10)).toBe('Outbound Messages (10)');
+  it('keeps root-level groups expanded', () => {
+    expect(canCollapseGroup(true)).toBe(false);
   });
 
-  it.each(['Quick Reference', 'Architecture', 'Resources'])('does not include the child count for %s', (title) => {
-    expect(getGroupLabel(title, 10)).toBe(title);
+  it('lets every group inside a resource sidebar collapse, whatever its size', () => {
+    expect(canCollapseGroup(false)).toBe(true);
+    expect(canCollapseGroup(false)).toBe(true);
   });
 
-  it('keeps top-level groups expanded', () => {
-    expect(canCollapseGroup(6, true)).toBe(false);
+  it('keeps groups marked as non-collapsible expanded regardless of their size', () => {
+    expect(canCollapseGroup(false, false)).toBe(false);
   });
 
-  it('only allows nested groups with more than five children to collapse', () => {
-    expect(canCollapseGroup(5, false)).toBe(false);
-    expect(canCollapseGroup(6, false)).toBe(true);
+  it('starts long lists collapsed and short ones open unless told otherwise', () => {
+    expect(getDefaultCollapsedState(5)).toBe(false);
+    expect(getDefaultCollapsedState(6)).toBe(true);
+    expect(getDefaultCollapsedState(6, false)).toBe(false);
+    expect(getDefaultCollapsedState(2, true)).toBe(true);
   });
 
-  it('keeps groups marked as non-collapsible expanded regardless of their size', () => {
-    expect(canCollapseGroup(100, false, false)).toBe(false);
+  it('always allows collapsing when an explicit collapsed state is set, overriding every other rule', () => {
+    expect(canCollapseGroup(false, true, true)).toBe(true);
+    expect(canCollapseGroup(false, true, false)).toBe(true);
+    expect(canCollapseGroup(true, false, true)).toBe(true);
   });
 });
 
@@ -40,6 +50,40 @@ describe('isGroupCollapsed', () => {
   it('uses an explicit expanded preference', () => {
     expect(isGroupCollapsed(true, 'outbound-messages', preferences(['outbound-messages']))).toBe(false);
   });
+
+  it('starts expanded when the group defaults to expanded, until the user collapses it', () => {
+    expect(isGroupCollapsed(true, 'owners', preferences(), false)).toBe(false);
+    expect(isGroupCollapsed(true, 'owners', preferences([], ['owners']), false)).toBe(true);
+  });
+});
+
+describe('toggleGroupCollapsed', () => {
+  it('records the user overriding a collapsed-by-default group, then clears it on the way back', () => {
+    const opened = toggleGroupCollapsed('g', preferences());
+    expect([...opened.expanded]).toEqual(['g']);
+    expect(opened.collapsed.size).toBe(0);
+
+    const closedAgain = toggleGroupCollapsed('g', opened);
+    expect(closedAgain.expanded.size).toBe(0);
+    expect([...closedAgain.collapsed]).toEqual(['g']);
+  });
+
+  it('records the user overriding an expanded-by-default group', () => {
+    const closed = toggleGroupCollapsed('g', preferences(), false);
+    expect([...closed.collapsed]).toEqual(['g']);
+    expect(isGroupCollapsed(true, 'g', closed, false)).toBe(true);
+
+    const reopened = toggleGroupCollapsed('g', closed, false);
+    expect(reopened.collapsed.size).toBe(0);
+    expect([...reopened.expanded]).toEqual(['g']);
+  });
+
+  it('does not mutate the previous preferences', () => {
+    const before = preferences();
+    toggleGroupCollapsed('g', before);
+    expect(before.expanded.size).toBe(0);
+    expect(before.collapsed.size).toBe(0);
+  });
 });
 
 describe('findNodeKeyByUrl', () => {