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

package/LICENSE

@@ -17,13 +17,13 @@ Licensed Work:        EventCatalog version 5.0 or later, including pre-releases,
                       and the examples directory. The Licensed Work is (c) 2026
                       EventCatalog Ltd.
 Additional Use Grant: You may make Production use of the Licensed Work if You
-                      are an Eligible User and Your use is not a Hosted
+                      qualify for Free Use and Your use is not a Hosted
                       Offering. Sections 1 to 7 below form part of this grant.
                       Capitalised terms are defined in section 6.
 
-                      1. Eligible Users
+                      1. Free Use
 
-                      You are an "Eligible User" if You are:
+                      You qualify for "Free Use" if You are:
 
                       (a) an individual using the Licensed Work for Your own
                           personal purposes, and not for or on behalf of any
@@ -47,9 +47,9 @@ Additional Use Grant: You may make Production use of the Licensed Work if You
 
                       2. Growing past the thresholds
 
-                      An Organisation that is an Eligible User under 1(b)
-                      remains one until ninety (90) days after the first of the
-                      following to happen:
+                      An Organisation that qualifies for Free Use under 1(b)
+                      continues to qualify until ninety (90) days after the
+                      first of the following to happen:
 
                       (a) the end of the first financial year in which its
                           Annual Revenue reaches USD 10,000,000; or
@@ -68,7 +68,7 @@ Additional Use Grant: You may make Production use of the Licensed Work if You
                       vendor), including building, customising, hosting or
                       distributing the Licensed Work or a catalog built with it
                       for that client, Your use for that client is permitted if
-                      the client is an Eligible User or holds a Commercial
+                      the client qualifies for Free Use or holds a Commercial
                       License covering that use. You may rely on a client's
                       written statement of its status unless You know it is
                       wrong. Your own use of the Licensed Work for Your own
@@ -76,7 +76,7 @@ Additional Use Grant: You may make Production use of the Licensed Work if You
 
                       4. Coming into compliance
 
-                      (a) If You stop being an Eligible User (for example
+                      (a) If You stop qualifying for Free Use (for example
                           because Your Evaluation Period ends), or You become
                           aware (including by notice from the Licensor) that
                           Your Production use is not permitted by this grant,
@@ -219,7 +219,8 @@ Additional Use Grant: You may make Production use of the Licensed Work if You
                           Public Open Source Projects.
 
                       "Commercial License" means a written license from the
-                      Licensor permitting Production use beyond this grant.
+                      Licensor, including one accepted online, permitting
+                      Production use beyond this grant.
 
                       7. Everything else
 
@@ -230,9 +231,9 @@ Additional Use Grant: You may make Production use of the Licensed Work if You
                       Work. The content of Your own catalog (the documentation,
                       schemas, diagrams and configuration You create) is Yours
                       and is not part of the Licensed Work.
-Change Date:          Four years after the first public release, including any
-                      pre-release, of any release in the same release series as
-                      the Licensed Work.
+Change Date:          Four years after the first public release (including any
+                      pre-release) in the same release series as the Licensed
+                      Work.
 
                       A "release series" is every release that shares the same
                       major and minor release number, including its pre-releases

package/dist/analytics/analytics.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(analytics_exports);
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,8 +1,8 @@
 import {
   raiseEvent
-} from "../chunk-JPT3QC5V.js";
+} from "../chunk-PI5YNZZZ.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-BO2HHVZ3.js";
+import "../chunk-I3XDOICA.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -176,7 +176,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,11 +1,11 @@
 import {
   log_build_default
-} from "../chunk-PLTLW45Q.js";
-import "../chunk-JPT3QC5V.js";
+} from "../chunk-WY6M3RPT.js";
+import "../chunk-AWOO63ME.js";
 import "../chunk-ZAZHAVKB.js";
+import "../chunk-PI5YNZZZ.js";
 import "../chunk-CPW6G62V.js";
-import "../chunk-AWOO63ME.js";
-import "../chunk-BO2HHVZ3.js";
+import "../chunk-I3XDOICA.js";
 import "../chunk-RFIXKATC.js";
 export {
   log_build_default as default

package/dist/{chunk-T75DOVFP.js → chunk-4KE3EUDJ.js}

@@ -1,6 +1,6 @@
 import {
   logger
-} from "./chunk-XA5W6DXX.js";
+} from "./chunk-OFK7U7BX.js";
 import {
   cleanup,
   getEventCatalogConfigFile

package/dist/{chunk-BO2HHVZ3.js → chunk-I3XDOICA.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-XA5W6DXX.js → chunk-OFK7U7BX.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BO2HHVZ3.js";
+} from "./chunk-I3XDOICA.js";
 
 // src/utils/cli-logger.ts
 import pc from "picocolors";

package/dist/{chunk-JPT3QC5V.js → chunk-PI5YNZZZ.js}

@@ -4,7 +4,7 @@ import {
 } from "./chunk-CPW6G62V.js";
 import {
   VERSION
-} from "./chunk-BO2HHVZ3.js";
+} from "./chunk-I3XDOICA.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-PLTLW45Q.js → chunk-WY6M3RPT.js}

@@ -1,18 +1,18 @@
 import {
-  raiseEvent
-} from "./chunk-JPT3QC5V.js";
+  getLicenseAnalytics
+} from "./chunk-AWOO63ME.js";
 import {
   countResources,
   hashCatalogContent,
   serializeCounts
 } from "./chunk-ZAZHAVKB.js";
+import {
+  raiseEvent
+} from "./chunk-PI5YNZZZ.js";
 import {
   TELEMETRY_REQUEST_TIMEOUT_MS,
   isTelemetryDisabled
 } from "./chunk-CPW6G62V.js";
-import {
-  getLicenseAnalytics
-} from "./chunk-AWOO63ME.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile

package/dist/constants.cjs

@@ -25,7 +25,7 @@ __export(constants_exports, {
 module.exports = __toCommonJS(constants_exports);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/constants.js

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-BO2HHVZ3.js";
+} from "./chunk-I3XDOICA.js";
 export {
   VERSION
 };

package/dist/eventcatalog.cjs

@@ -181,7 +181,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;
@@ -2980,7 +2980,7 @@ var resolveDevPort = async ({ projectDir }) => {
 };
 var startDevPrewarm = ({
   port = 3e3,
-  paths = ["/ping", "/"],
+  paths = ["/"],
   retries = 80,
   intervalMs = 250,
   initialDelayMs = 500
@@ -2989,10 +2989,13 @@ var startDevPrewarm = ({
   const hit = (requestPath) => new Promise((resolve2) => {
     const req = import_node_http.default.get(
       {
-        hostname: "127.0.0.1",
+        // Not 127.0.0.1: the dev server can listen on IPv6 only ([::1]), which refused
+        // every prewarm request
+        hostname: "localhost",
         port,
         path: requestPath,
-        timeout: 1200
+        // A refused connection fails at once; once connected, let the first render finish
+        timeout: 3e4
       },
       (res) => {
         res.resume();
@@ -3251,7 +3254,9 @@ program.command("dev").description("Run development server of EventCatalog").opt
       });
       startDevPrewarm({
         port: prewarmPort,
-        paths: ["/ping", "/"]
+        // Renders the homepage before anyone opens it. Requests stop at the first response,
+        // so a probe path like /ping first would leave the homepage cold.
+        paths: ["/"]
       });
     }
     await runCommandWithFilteredOutput({

package/dist/eventcatalog.js

@@ -1,29 +1,28 @@
-import {
-  log_build_default
-} from "./chunk-PLTLW45Q.js";
-import "./chunk-JPT3QC5V.js";
-import "./chunk-ZAZHAVKB.js";
-import "./chunk-CPW6G62V.js";
 import {
   runMigrations
 } from "./chunk-XUAF2H54.js";
 import "./chunk-CA4U2JP7.js";
+import {
+  log_build_default
+} from "./chunk-WY6M3RPT.js";
 import {
   getLicenseStatus,
   printLicenseStatus
 } from "./chunk-AWOO63ME.js";
+import "./chunk-ZAZHAVKB.js";
 import {
   FederationConflictError,
   FederationDiagnosticError,
   federateCatalog
-} from "./chunk-ZEY2XUJN.js";
+} from "./chunk-KHACCTW2.js";
+import "./chunk-WRNH5C3U.js";
+import "./chunk-5EPNFDT5.js";
+import "./chunk-A2RZR3U4.js";
+import "./chunk-R7Z5ALYI.js";
 import {
   getFederationDiagnosticCounts,
   getVisibleFederationDiagnostics
 } from "./chunk-JJPB6EOZ.js";
-import "./chunk-WRNH5C3U.js";
-import "./chunk-5EPNFDT5.js";
-import "./chunk-A2RZR3U4.js";
 import "./chunk-SDZQJTJW.js";
 import "./chunk-352FGP6W.js";
 import {
@@ -34,10 +33,10 @@ import {
 } from "./chunk-MDWB5HLO.js";
 import {
   generate
-} from "./chunk-T75DOVFP.js";
+} from "./chunk-4KE3EUDJ.js";
 import {
   logger
-} from "./chunk-XA5W6DXX.js";
+} from "./chunk-OFK7U7BX.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-36RYTYT5.js";
@@ -51,7 +50,8 @@ import {
 import {
   watch
 } from "./chunk-U63GDPPY.js";
-import "./chunk-R7Z5ALYI.js";
+import "./chunk-PI5YNZZZ.js";
+import "./chunk-CPW6G62V.js";
 import {
   getAstroConfigPath
 } from "./chunk-VIJJ7JKH.js";
@@ -67,7 +67,7 @@ import {
 } from "./chunk-LFQJXLHG.js";
 import {
   VERSION
-} from "./chunk-BO2HHVZ3.js";
+} from "./chunk-I3XDOICA.js";
 import {
   getEventCatalogConfigFile,
   verifyRequiredFieldsAreInCatalogConfigFile
@@ -669,7 +669,7 @@ var resolveDevPort = async ({ projectDir }) => {
 };
 var startDevPrewarm = ({
   port = 3e3,
-  paths = ["/ping", "/"],
+  paths = ["/"],
   retries = 80,
   intervalMs = 250,
   initialDelayMs = 500
@@ -678,10 +678,13 @@ var startDevPrewarm = ({
   const hit = (requestPath) => new Promise((resolve) => {
     const req = http.get(
       {
-        hostname: "127.0.0.1",
+        // Not 127.0.0.1: the dev server can listen on IPv6 only ([::1]), which refused
+        // every prewarm request
+        hostname: "localhost",
         port,
         path: requestPath,
-        timeout: 1200
+        // A refused connection fails at once; once connected, let the first render finish
+        timeout: 3e4
       },
       (res) => {
         res.resume();
@@ -940,7 +943,9 @@ program.command("dev").description("Run development server of EventCatalog").opt
       });
       startDevPrewarm({
         port: prewarmPort,
-        paths: ["/ping", "/"]
+        // Renders the homepage before anyone opens it. Requests stop at the first response,
+        // so a probe path like /ping first would leave the homepage cold.
+        paths: ["/"]
       });
     }
     await runCommandWithFilteredOutput({

package/dist/federation/federate.js

@@ -2,14 +2,14 @@ import {
   FederationConflictError,
   FederationDiagnosticError,
   federateCatalog
-} from "../chunk-ZEY2XUJN.js";
-import "../chunk-JJPB6EOZ.js";
+} from "../chunk-KHACCTW2.js";
 import "../chunk-WRNH5C3U.js";
 import "../chunk-5EPNFDT5.js";
 import "../chunk-A2RZR3U4.js";
+import "../chunk-R7Z5ALYI.js";
+import "../chunk-JJPB6EOZ.js";
 import "../chunk-SDZQJTJW.js";
 import "../chunk-352FGP6W.js";
-import "../chunk-R7Z5ALYI.js";
 import "../chunk-RFIXKATC.js";
 export {
   FederationConflictError,

package/dist/generate.cjs

@@ -112,7 +112,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-T75DOVFP.js";
-import "./chunk-XA5W6DXX.js";
-import "./chunk-BO2HHVZ3.js";
+} from "./chunk-4KE3EUDJ.js";
+import "./chunk-OFK7U7BX.js";
+import "./chunk-I3XDOICA.js";
 import "./chunk-RFIXKATC.js";
 export {
   generate

package/dist/utils/cli-logger.cjs

@@ -36,7 +36,7 @@ module.exports = __toCommonJS(cli_logger_exports);
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "5.0.0-beta.13";
+var version = "5.0.0-beta.14";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-XA5W6DXX.js";
-import "../chunk-BO2HHVZ3.js";
+} from "../chunk-OFK7U7BX.js";
+import "../chunk-I3XDOICA.js";
 export {
   logger
 };

package/eventcatalog/astro.config.mjs

@@ -35,6 +35,8 @@ import config from './src/utils/eventcatalog-config/source.ts';
 import preprocessExpressiveCodeConfig from './integrations/expressive-code-config.mjs';
 import catalogAssets from './integrations/catalog-assets.mjs';
 import runtimeDependencies from './integrations/runtime-dependencies.mjs';
+import stableDependencyOrder from './integrations/stable-dependency-order.mjs';
+import skipStartupReload from './integrations/skip-startup-reload.mjs';
 import { getRuntimePaths } from './integrations/runtime-paths.mjs';
 import { collectClientDependencies } from './integrations/client-dependencies.mjs';
 
@@ -166,6 +168,8 @@ export default defineConfig({
     },
     plugins: [
       runtimeDependencies(),
+      stableDependencyOrder(),
+      skipStartupReload(),
       tailwindcss(),
       ...(await eventCatalogLikeC4(projectDirectory)),
       ...(config.trailingSlash === true ? [astroTrailingSlashEndpointFix()] : []),
@@ -224,7 +228,15 @@ export default defineConfig({
     },
     optimizeDeps: {
       exclude: [],
-      include: collectClientDependencies(),
+      include: [
+        ...collectClientDependencies(),
+        // <ClientRouter /> imports these from a virtual module the dependency scan can't follow,
+        // so without them every cold start re-bundles on the first page and reloads it
+        'astro/virtual-modules/transitions-events.js',
+        'astro/virtual-modules/transitions-router.js',
+        'astro/virtual-modules/transitions-swap-functions.js',
+        'astro/virtual-modules/transitions-types.js',
+      ],
     },
   },
 });

package/eventcatalog/integrations/skip-startup-reload.mjs

@@ -0,0 +1,31 @@
+// Astro writes its content data store as the dev server starts, which sends the browser a
+// full reload. With no browser connected yet, Vite holds that reload and hands it to the
+// first page that connects, so the first page opened after every start loaded twice.
+// A reload sent before any page has been served has nothing to refresh (a tab left open
+// from the previous run reloads itself when it reconnects), so drop those. Once a page has
+// been requested, reloads pass through as usual.
+
+const isFullReload = (payload) => typeof payload === 'object' && payload?.type === 'full-reload';
+
+export default function skipStartupReload() {
+  return {
+    name: 'eventcatalog:skip-startup-reload',
+    apply: 'serve',
+    configureServer(server) {
+      let pageRequested = false;
+      server.middlewares.use((req, _res, next) => {
+        // Browser navigations ask for HTML; the CLI's prewarm request doesn't
+        if (!pageRequested && req.headers.accept?.includes('text/html')) pageRequested = true;
+        next();
+      });
+
+      for (const channel of new Set([server.ws, server.environments?.client?.hot].filter(Boolean))) {
+        const send = channel.send.bind(channel);
+        channel.send = (...args) => {
+          if (!pageRequested && isFullReload(args[0])) return;
+          return send(...args);
+        };
+      }
+    },
+  };
+}

package/eventcatalog/integrations/stable-dependency-order.mjs

@@ -0,0 +1,29 @@
+// Astro crawls framework packages with vitefu, which looks them up concurrently and lists
+// each one in `resolve.external` / `resolve.noExternal` as its lookup finishes, so the
+// order changes from one start to the next. Vite hashes these lists unsorted to decide
+// whether its pre-bundled dependencies are still valid, so every `eventcatalog dev` saw a
+// "changed" config and re-bundled all of them. Only membership matters in these lists, so
+// sorting them keeps the hash (and the dependency cache) stable across starts.
+
+const byName = (a, b) => {
+  const left = String(a);
+  const right = String(b);
+  return left < right ? -1 : left > right ? 1 : 0;
+};
+
+const sortResolveLists = (resolve) => {
+  if (Array.isArray(resolve?.external)) resolve.external.sort(byName);
+  if (Array.isArray(resolve?.noExternal)) resolve.noExternal.sort(byName);
+};
+
+export default function stableDependencyOrder() {
+  return {
+    name: 'eventcatalog:stable-dependency-order',
+    apply: 'serve',
+    configResolved(config) {
+      sortResolveLists(config.resolve);
+      sortResolveLists(config.ssr);
+      for (const environment of Object.values(config.environments ?? {})) sortResolveLists(environment.resolve);
+    },
+  };
+}

package/eventcatalog/src/components/CatalogGraph/CatalogForceGraph.tsx

@@ -170,6 +170,16 @@ const nodeRadius = (degree: number, isHub = false) =>
 /** Above this node count, expensive extras (collision force) are disabled. */
 const LARGE_GRAPH_NODE_COUNT = 1500;
 
+/**
+ * The first layout settles before it paints instead of animating into place for ~5s: ticks
+ * run in short slices across frames (no long tasks) until it settles, ~40ms of work for 100
+ * nodes. Big catalogs stop once ticking has taken the work limit, paint past their largest
+ * moves and animate the rest. The limit counts ticking time, not elapsed time, so a page busy
+ * hydrating other islands doesn't cut the settle short.
+ */
+const INITIAL_SETTLE_SLICE_MS = 12;
+const INITIAL_SETTLE_WORK_LIMIT_MS = 400;
+
 /** Sprite resolution for node icons (drawn scaled-down, so keep it crisp) */
 const ICON_SPRITE_SIZE = 64;
 
@@ -617,6 +627,10 @@ const CatalogForceGraph = ({
     // normal-sized, whatever the lens's usual hubs are
     const isHub = (d: SimNode) => (focusKey ? d.key === focusKey : hubs.has(d.collection));
 
+    // Later layouts (lens, focus and filter changes) animate from the previous positions
+    const isFirstLayout = positionsRef.current.size === 0;
+    // Nothing paints until the first layout has settled (see INITIAL_SETTLE_SLICE_MS)
+    let settling = isFirstLayout;
     const visibleNodes: SimNode[] = viewNodes
       .filter((n) => !hiddenCollections.has(n.collection))
       .map((n) => ({ ...n, degree: 0, ...positionsRef.current.get(n.key) }));
@@ -734,6 +748,7 @@ const CatalogForceGraph = ({
     };
 
     const draw = () => {
+      if (settling) return;
       context.save();
       context.setTransform(devicePixelRatio, 0, 0, devicePixelRatio, 0, 0);
       context.clearRect(0, 0, width, height);
@@ -1014,6 +1029,29 @@ const CatalogForceGraph = ({
       );
     }
 
+    // Settle the first layout before it paints rather than animating it into place
+    let settleFrame: number | undefined;
+    if (isFirstLayout) {
+      simulation.stop();
+      let workLeft = INITIAL_SETTLE_WORK_LIMIT_MS;
+      const settle = () => {
+        const sliceStart = performance.now();
+        const sliceEnd = sliceStart + Math.min(INITIAL_SETTLE_SLICE_MS, workLeft);
+        while (simulation.alpha() > simulation.alphaMin() && performance.now() < sliceEnd) simulation.tick();
+        workLeft -= performance.now() - sliceStart;
+        if (simulation.alpha() > simulation.alphaMin() && workLeft > 0) {
+          settleFrame = requestAnimationFrame(settle);
+          return;
+        }
+        settling = false;
+        // Settled: paint it as is (restarting would run one tick more than the animated
+        // layout). Otherwise paint and animate whatever is left.
+        if (simulation.alpha() <= simulation.alphaMin()) fitToView();
+        else simulation.restart();
+      };
+      settleFrame = requestAnimationFrame(settle);
+    }
+
     const findNode = (canvasX: number, canvasY: number): SimNode | null => {
       if (Number.isNaN(canvasX) || Number.isNaN(canvasY)) return null;
       const x = transform.invertX(canvasX);
@@ -1219,6 +1257,7 @@ const CatalogForceGraph = ({
       for (const node of visibleNodes) {
         if (node.x !== undefined && node.y !== undefined) positionsRef.current.set(node.key, { x: node.x, y: node.y });
       }
+      if (settleFrame !== undefined) cancelAnimationFrame(settleFrame);
       simulation.stop();
       // The tooltip outlives this effect — never leave it showing stale content
       tooltip.style.opacity = '0';

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/package.json

@@ -7,7 +7,7 @@
   },
   "license": "BUSL-1.1",
   "type": "module",
-  "version": "5.0.0-beta.13",
+  "version": "5.0.0-beta.14",
   "publishConfig": {
     "access": "public"
   },
@@ -140,9 +140,9 @@
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.33",
     "zod": "^4.3.6",
+    "@eventcatalog/sdk": "2.30.0-beta.1",
     "@eventcatalog/linter": "1.2.0-beta.2",
-    "@eventcatalog/visualiser": "^5.0.0-beta.6",
-    "@eventcatalog/sdk": "2.30.0-beta.1"
+    "@eventcatalog/visualiser": "^5.0.0-beta.6"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.10",

package/dist/{chunk-ZEY2XUJN.js → chunk-KHACCTW2.js}

@@ -1,7 +1,3 @@
-import {
-  getFederationDiagnostics,
-  resolveFederationRules
-} from "./chunk-JJPB6EOZ.js";
 import {
   withFederationOutputTransaction
 } from "./chunk-WRNH5C3U.js";
@@ -14,6 +10,10 @@ import {
 import {
   createFederationContentCache
 } from "./chunk-R7Z5ALYI.js";
+import {
+  getFederationDiagnostics,
+  resolveFederationRules
+} from "./chunk-JJPB6EOZ.js";
 import {
   getEventCatalogConfigFile
 } from "./chunk-RFIXKATC.js";