@eventcatalog/core 5.0.0-beta.9 → 5.0.0

package/eventcatalog/src/components/Settings/LlmAccessSettingsForm.tsx

@@ -64,44 +64,49 @@ export const LlmAccessSettingsForm = ({ canEdit, initial, apiBase, llmsTxtUrl, l
   };
 
   return (
-    <form onSubmit={(e) => e.preventDefault()} className="divide-y divide-[rgb(var(--ec-page-border))]">
+    <>
       <Toaster richColors closeButton position="bottom-right" theme="system" />
-      {!canEdit && (
-        <div className="pb-6">
-          <ReadOnlyBanner />
-        </div>
-      )}
-
-      <Row
-        title="llms.txt"
-        description="Generate llms.txt files so tools like Claude, ChatGPT, and Cursor can read your catalog at /llms.txt."
-        canEdit={canEdit}
-        dirty={dirty}
-        saving={saving}
-        onSave={save}
+      <form
+        onSubmit={(e) => e.preventDefault()}
+        className="divide-y divide-[rgb(var(--ec-page-border))] border-t border-[rgb(var(--ec-page-border))]"
       >
-        <ToggleRow
-          icon={<Bot className="h-4 w-4" aria-hidden />}
-          label={llmsTxtEnabled ? 'Enabled' : 'Disabled'}
-          hint={
-            llmsTxtEnabled ? 'AI tools can read your catalog at /llms.txt.' : 'AI tools will not be able to read your catalog.'
-          }
-          checked={llmsTxtEnabled}
-          disabled={!canEdit}
-          onChange={setLlmsTxtEnabled}
-        />
-        {llmsTxtEnabled && <LlmsTxtPreview url={llmsTxtUrl} fullUrl={llmsFullTxtUrl} />}
-      </Row>
+        {!canEdit && (
+          <div className="pb-6">
+            <ReadOnlyBanner />
+          </div>
+        )}
 
-      <Row
-        title="schemas.txt"
-        description="Give LLMs access to every schema across your organization in one place — events, commands, queries, and services."
-        canEdit={false}
-        dirty={false}
-      >
-        <SchemasTxtAvailable url={schemasTxtUrl} />
-      </Row>
-    </form>
+        <Row
+          title="llms.txt"
+          description="Generate llms.txt files so tools like Claude, ChatGPT, and Cursor can read your catalog at /llms.txt."
+          canEdit={canEdit}
+          dirty={dirty}
+          saving={saving}
+          onSave={save}
+        >
+          <ToggleRow
+            icon={<Bot className="h-4 w-4" aria-hidden />}
+            label={llmsTxtEnabled ? 'Enabled' : 'Disabled'}
+            hint={
+              llmsTxtEnabled ? 'AI tools can read your catalog at /llms.txt.' : 'AI tools will not be able to read your catalog.'
+            }
+            checked={llmsTxtEnabled}
+            disabled={!canEdit}
+            onChange={setLlmsTxtEnabled}
+          />
+          {llmsTxtEnabled && <LlmsTxtPreview url={llmsTxtUrl} fullUrl={llmsFullTxtUrl} />}
+        </Row>
+
+        <Row
+          title="schemas.txt"
+          description="Give LLMs access to every schema across your organization in one place — events, commands, queries, and services."
+          canEdit={false}
+          dirty={false}
+        >
+          <SchemasTxtAvailable url={schemasTxtUrl} />
+        </Row>
+      </form>
+    </>
   );
 };
 

package/eventcatalog/src/components/Settings/LogoUpload.tsx

@@ -75,7 +75,7 @@ export const LogoUpload = ({ canEdit, initialSrc, apiUrl, onSrcChange }: LogoUpl
       onDrop={onDrop}
       className={`relative flex items-center gap-5 rounded-lg border border-dashed px-4 py-4 transition-colors ${
         dragOver
-          ? 'border-[rgb(var(--ec-accent)/0.6)] bg-[rgb(var(--ec-accent-subtle)/0.4)]'
+          ? 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.04)]'
           : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg)/0.4)]'
       }`}
     >

package/eventcatalog/src/components/Settings/McpSettingsForm.tsx

@@ -26,7 +26,8 @@ interface Props {
 
 export const McpSettingsForm = ({ inSSR, mcpUrl, domainServers }: Props) => {
   return (
-    <div className="divide-y divide-[rgb(var(--ec-page-border))]">
+    // A top border, as on the other settings pages
+    <div className="divide-y divide-[rgb(var(--ec-page-border))] border-t border-[rgb(var(--ec-page-border))]">
       <Row
         title="Catalog MCP Server"
         description="Connect AI agents (Claude, Cursor, VS Code and any MCP client) to every resource in your catalog: domains, services, messages, flows, schemas and the teams that own them."
@@ -63,7 +64,7 @@ const LivePill = () => (
 const CatalogServer = ({ url }: { url: string }) => (
   <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg,var(--ec-page-bg)))]">
     <div className="flex items-start gap-3 px-4 py-3.5">
-      <span className="flex h-9 w-9 flex-shrink-0 items-center justify-center rounded-lg border border-[rgb(var(--ec-accent)/0.3)] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent))]">
+      <span className="flex h-9 w-9 flex-shrink-0 items-center justify-center rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.05)] text-[rgb(var(--ec-page-text))]">
         <Library className="h-4 w-4" aria-hidden />
       </span>
       <div className="min-w-0 flex-1">
@@ -83,7 +84,7 @@ const CatalogServer = ({ url }: { url: string }) => (
         href={MCP_DOCS_URL}
         target="_blank"
         rel="noreferrer"
-        className="mt-3 inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-accent))] hover:underline"
+        className="mt-3 inline-flex items-center gap-1 text-[12px] font-medium text-[rgb(var(--ec-page-text))] hover:underline"
       >
         How to connect a client
         <ArrowUpRight className="h-3.5 w-3.5" aria-hidden />
@@ -100,7 +101,7 @@ const DomainServers = ({ servers }: { servers: DomainMcpServer[] }) => (
           <a
             href={server.docsUrl}
             title={server.summary}
-            className="inline-flex min-w-0 items-center gap-2 text-[13px] font-medium text-[rgb(var(--ec-page-text))] hover:text-[rgb(var(--ec-accent))]"
+            className="inline-flex min-w-0 items-center gap-2 text-[13px] font-medium text-[rgb(var(--ec-page-text))] hover:underline"
           >
             <Boxes className="h-3.5 w-3.5 flex-shrink-0 self-center text-[rgb(var(--ec-icon-color))]" aria-hidden />
             <span className="truncate">{server.name}</span>
@@ -114,15 +115,15 @@ const DomainServers = ({ servers }: { servers: DomainMcpServer[] }) => (
 );
 
 const McpNeedsSSR = () => (
-  <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-accent)/0.4)] bg-gradient-to-br from-[rgb(var(--ec-accent)/0.1)] via-[rgb(var(--ec-accent)/0.05)] to-transparent">
+  <div className="overflow-hidden rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.03)]">
     <div className="flex items-start gap-3 px-4 py-3.5">
-      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] text-[rgb(var(--ec-accent))]">
+      <span className="flex h-8 w-8 flex-shrink-0 items-center justify-center rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.05)] text-[rgb(var(--ec-page-text))]">
         <ServerCog className="h-4 w-4" aria-hidden />
       </span>
       <div className="flex-1 min-w-0">
         <div className="flex items-center gap-2">
           <p className="text-[13px] font-semibold text-[rgb(var(--ec-page-text))]">Server output mode required</p>
-          <span className="inline-flex items-center gap-1 rounded-full border border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent)/0.1)] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent))]">
+          <span className="inline-flex items-center gap-1 rounded-full border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.05)] px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-page-text))]">
             SSR
           </span>
         </div>
@@ -134,7 +135,7 @@ const McpNeedsSSR = () => (
             href={MCP_DOCS_URL}
             target="_blank"
             rel="noreferrer"
-            className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-accent))] px-3 py-1.5 text-[12px] font-semibold text-white shadow-sm transition-colors hover:bg-[rgb(var(--ec-accent-hover))]"
+            className="inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-page-text))] px-3 py-1.5 text-[12px] font-semibold text-[rgb(var(--ec-page-bg))] shadow-sm transition-colors hover:opacity-85"
           >
             MCP setup guide
             <ExternalLink className="h-3 w-3" aria-hidden />

package/eventcatalog/src/components/Settings/Row.tsx

@@ -3,7 +3,7 @@ import { AlertCircle } from 'lucide-react';
 export const cn = (...parts: Array<string | false | undefined | null>): string => parts.filter(Boolean).join(' ');
 
 export const inputBase =
-  'block w-full rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] px-3 py-2 text-[13px] text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-page-text-muted)/0.7)] transition-colors focus:border-[rgb(var(--ec-accent)/0.6)] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-accent)/0.25)] disabled:cursor-not-allowed disabled:opacity-60';
+  'block w-full rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-input-bg,var(--ec-page-bg)))] px-3 py-2 text-[13px] text-[rgb(var(--ec-page-text))] placeholder:text-[rgb(var(--ec-page-text-muted)/0.7)] transition-colors focus:border-[rgb(var(--ec-page-text)/0.5)] focus:outline-none focus:ring-2 focus:ring-[rgb(var(--ec-page-text)/0.15)] disabled:cursor-not-allowed disabled:opacity-60';
 
 export const monoInput = 'font-mono text-[12.5px] tracking-tight';
 
@@ -11,7 +11,9 @@ export const inputError = 'border-red-500/70 focus:border-red-500 focus:ring-red
 
 interface RowProps {
   title: string;
-  description: string;
+  description: React.ReactNode;
+  /** Shown under the description, in the left column */
+  aside?: React.ReactNode;
   canEdit: boolean;
   dirty: boolean;
   saving?: boolean;
@@ -20,13 +22,14 @@ interface RowProps {
   children: React.ReactNode;
 }
 
-export const Row = ({ title, description, canEdit, dirty, saving, onSave, error, children }: RowProps) => (
+export const Row = ({ title, description, aside, canEdit, dirty, saving, onSave, error, children }: RowProps) => (
   <section className="grid grid-cols-1 gap-6 py-8 md:grid-cols-[minmax(0,_18rem)_minmax(0,_1fr)] md:gap-12">
     <header className="space-y-1.5">
       <h3 className="text-[14px] font-semibold tracking-tight text-[rgb(var(--ec-page-text))]">{title}</h3>
       <p className="text-[13px] leading-relaxed text-[rgb(var(--ec-content-text-muted,var(--ec-page-text-muted)))]">
         {description}
       </p>
+      {aside && <div className="pt-3">{aside}</div>}
     </header>
     <div className="space-y-2.5">
       {children}
@@ -45,7 +48,7 @@ export const Row = ({ title, description, canEdit, dirty, saving, onSave, error,
             className={cn(
               'inline-flex items-center gap-1.5 rounded-md border px-3 py-1.5 text-[12px] font-medium transition-colors',
               dirty && !saving
-                ? 'border-[rgb(var(--ec-accent)/0.5)] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-accent-text))] hover:bg-[rgb(var(--ec-accent-subtle)/0.8)]'
+                ? 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-text)/0.05)] text-[rgb(var(--ec-page-text))] hover:bg-[rgb(var(--ec-page-text)/0.08)]'
                 : 'border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] text-[rgb(var(--ec-page-text-muted))]',
               'disabled:cursor-not-allowed disabled:opacity-60'
             )}

package/eventcatalog/src/components/Settings/SettingsShared.tsx

@@ -32,7 +32,7 @@ export const UrlPanel = ({ url }: UrlPanelProps) => {
         href={url}
         target="_blank"
         rel="noreferrer"
-        className="flex-1 truncate rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-2.5 py-1.5 font-mono text-[12px] text-[rgb(var(--ec-page-text))] transition-colors hover:border-[rgb(var(--ec-accent)/0.5)] hover:text-[rgb(var(--ec-accent))]"
+        className="flex-1 truncate rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-page-bg))] px-2.5 py-1.5 font-mono text-[12px] text-[rgb(var(--ec-page-text))] transition-colors hover:border-[rgb(var(--ec-page-text)/0.4)]"
       >
         {fullUrl}
       </a>
@@ -72,13 +72,13 @@ export const Toggle = ({ checked, disabled, onChange }: ToggleProps) => (
     onClick={() => onChange(!checked)}
     className={cn(
       'relative inline-flex h-5 w-9 flex-shrink-0 cursor-pointer items-center rounded-full transition-colors',
-      checked ? 'bg-[rgb(var(--ec-accent))]' : 'bg-[rgb(var(--ec-page-text-muted)/0.35)]',
+      checked ? 'bg-[rgb(var(--ec-page-text))]' : 'bg-[rgb(var(--ec-page-text-muted)/0.35)]',
       disabled && 'cursor-not-allowed opacity-50'
     )}
   >
     <span
       className={cn(
-        'inline-block h-3.5 w-3.5 transform rounded-full bg-white shadow-sm transition-transform',
+        'inline-block h-3.5 w-3.5 transform rounded-full bg-[rgb(var(--ec-page-bg))] shadow-sm transition-transform',
         checked ? 'translate-x-[1.125rem]' : 'translate-x-[0.1875rem]'
       )}
     />

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>