@eventcatalog/core 4.0.6 → 4.1.0

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

@@ -4,6 +4,7 @@ import JSONSchemaViewer from '@components/SchemaExplorer/JSONSchemaViewer';
 import { Code } from 'astro-expressive-code/components';
 import { isPrivateRemoteSchemaEnabled } from '@utils/feature';
 import { resolveTemplateVariables } from '@utils/remote-file';
+import { resolveSchemaRefs } from '@utils/json-schema-refs';
 
 const {
   url,
@@ -89,6 +90,10 @@ try {
   if (isValidJSON(content)) {
     contentType = 'json';
     processedData = JSON.parse(content);
+    processedData = await resolveSchemaRefs(processedData, {
+      baseUrl: String(resolvedUrl),
+      headers: resolvedHeaders as HeadersInit,
+    });
 
     // Check if it's a JSON Schema
     isSchema = isJSONSchema(processedData);

package/eventcatalog/src/components/SchemaExplorer/DiffViewer.tsx

@@ -122,10 +122,10 @@ export default function DiffViewer({ diffs, onOpenFullscreen, apiAccessEnabled =
       {isDark && <style dangerouslySetInnerHTML={{ __html: DIFF_DARK_STYLES }} />}
       <div className="mb-5 flex items-start justify-between">
         <div className="flex-1">
-          <h3 className="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-1">Version History</h3>
+          <h3 className="text-base font-semibold text-[rgb(var(--ec-page-text))] mb-1">Version Comparison</h3>
           <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">
             {apiAccessEnabled
-              ? `${diffs.length} version comparison${diffs.length !== 1 ? 's' : ''}`
+              ? `${diffs.length} selected comparison${diffs.length !== 1 ? 's' : ''}`
               : 'Compare schema versions side-by-side'}
           </p>
         </div>
@@ -142,21 +142,19 @@ export default function DiffViewer({ diffs, onOpenFullscreen, apiAccessEnabled =
       </div>
       {apiAccessEnabled ? (
         <div className={`space-y-6 ${isDark ? 'diff-dark-mode' : ''}`}>
-          {diffs.map((diff, index) => (
+          {diffs.map((diff) => (
             <div
-              key={`${diff.newerVersion}-${diff.olderVersion}`}
+              key={`${diff.fromVersion}-${diff.toVersion}`}
               className="border border-[rgb(var(--ec-page-border))] rounded-lg overflow-hidden"
             >
               <div className="bg-[rgb(var(--ec-content-hover))] border-b border-[rgb(var(--ec-page-border))] px-4 py-2.5">
                 <div className="flex items-center justify-between">
                   <div className="text-sm">
-                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.newerVersion}</span>
+                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.fromVersion}</span>
                     <span className="text-[rgb(var(--ec-page-text-muted))] mx-2">&rarr;</span>
-                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.olderVersion}</span>
+                    <span className="font-semibold text-[rgb(var(--ec-page-text))]">v{diff.toVersion}</span>
                   </div>
-                  <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">
-                    {index === 0 ? 'Latest change' : `${index + 1} version${index + 1 !== 1 ? 's' : ''} ago`}
-                  </span>
+                  <span className="text-xs text-[rgb(var(--ec-page-text-muted))]">Selected comparison</span>
                 </div>
               </div>
               <div className="relative">

package/eventcatalog/src/components/SchemaExplorer/SchemaDetailsPanel.tsx

@@ -64,43 +64,70 @@ export default function SchemaDetailsPanel({
   const consumers = message.data.consumers || [];
   const filename = message.data.schemaPath?.split('/').pop() || `${message.data.id}.${ext || 'json'}`;
 
-  // Generate diffs between all consecutive versions
-  const allDiffs: VersionDiff[] = useMemo(() => {
-    const diffs: VersionDiff[] = [];
-    if (!hasMultipleVersions) return diffs;
-
-    for (let i = 0; i < availableVersions.length - 1; i++) {
-      const newerVersion = availableVersions[i];
-      const olderVersion = availableVersions[i + 1];
-
-      if (newerVersion.schemaContent && olderVersion.schemaContent) {
-        const diff = Diff.createTwoFilesPatch(
-          `v${olderVersion.data.version}`,
-          `v${newerVersion.data.version}`,
-          olderVersion.schemaContent,
-          newerVersion.schemaContent,
-          '',
-          '',
-          { context: 3 }
-        );
-
-        const diffHtml = html(diff, {
-          drawFileList: false,
-          matching: 'lines',
-          outputFormat: 'side-by-side',
-        });
-
-        diffs.push({
-          newerVersion: newerVersion.data.version,
-          olderVersion: olderVersion.data.version,
-          diffHtml,
-          newerContent: newerVersion.schemaContent,
-          olderContent: olderVersion.schemaContent,
-        });
-      }
-    }
-    return diffs;
-  }, [availableVersions]);
+  const uniqueAvailableVersions = useMemo(
+    () =>
+      availableVersions.filter(
+        (version, index, versions) => versions.findIndex((item) => item.data.version === version.data.version) === index
+      ),
+    [availableVersions]
+  );
+  const defaultToVersion = uniqueAvailableVersions[0]?.data.version || '';
+  const defaultFromVersion = uniqueAvailableVersions[1]?.data.version || defaultToVersion;
+  const [diffFromVersion, setDiffFromVersion] = useState(defaultFromVersion);
+  const [diffToVersion, setDiffToVersion] = useState(defaultToVersion);
+  const schemaResourceKey = [
+    message.collection,
+    message.data.id,
+    message.specType || '',
+    message.specFilenameWithoutExtension || message.specName || '',
+  ].join(':');
+
+  useEffect(() => {
+    setDiffFromVersion(defaultFromVersion);
+    setDiffToVersion(defaultToVersion);
+    setIsDiffModalOpen(false);
+  }, [schemaResourceKey, defaultFromVersion, defaultToVersion]);
+
+  const diffFromItem = useMemo(
+    () => uniqueAvailableVersions.find((version) => version.data.version === diffFromVersion),
+    [diffFromVersion, uniqueAvailableVersions]
+  );
+  const diffToItem = useMemo(
+    () => uniqueAvailableVersions.find((version) => version.data.version === diffToVersion),
+    [diffToVersion, uniqueAvailableVersions]
+  );
+  const hasDiffFromContent = !!diffFromItem?.schemaContent?.trim();
+  const hasDiffToContent = !!diffToItem?.schemaContent?.trim();
+  const selectedDiff: VersionDiff | null = useMemo(() => {
+    if (!diffFromItem || !diffToItem) return null;
+    if (diffFromItem.data.version === diffToItem.data.version) return null;
+    if (!diffFromItem.schemaContent?.trim() || !diffToItem.schemaContent?.trim()) return null;
+
+    const diff = Diff.createTwoFilesPatch(
+      `v${diffFromItem.data.version}`,
+      `v${diffToItem.data.version}`,
+      diffFromItem.schemaContent,
+      diffToItem.schemaContent,
+      '',
+      '',
+      { context: 3 }
+    );
+
+    const diffHtml = html(diff, {
+      drawFileList: false,
+      matching: 'lines',
+      outputFormat: 'side-by-side',
+    });
+
+    return {
+      fromVersion: diffFromItem.data.version,
+      toVersion: diffToItem.data.version,
+      diffHtml,
+      fromContent: diffFromItem.schemaContent,
+      toContent: diffToItem.schemaContent,
+    };
+  }, [diffFromItem, diffToItem]);
+  const selectedDiffs = selectedDiff ? [selectedDiff] : [];
 
   // Check if this is a JSON schema
   const parsedSchema = useMemo(() => {
@@ -212,7 +239,7 @@ export default function SchemaDetailsPanel({
   if (examples.length > 0) {
     tabs.push({ id: 'examples', label: 'Usage Examples', icon: <BookOpenIcon className="h-3.5 w-3.5" /> });
   }
-  if (allDiffs.length > 0) {
+  if (hasMultipleVersions) {
     tabs.push({ id: 'diff', label: 'Changes', icon: <ClockIcon className="h-3.5 w-3.5" /> });
   }
   tabs.push({ id: 'api', label: 'API', icon: <GlobeAltIcon className="h-3.5 w-3.5" /> });
@@ -341,8 +368,67 @@ export default function SchemaDetailsPanel({
               copiedId={copiedId}
               apiAccessEnabled={apiAccessEnabled}
             />
-          ) : activeTab === 'diff' && allDiffs.length > 0 ? (
-            <DiffViewer diffs={allDiffs} onOpenFullscreen={() => setIsDiffModalOpen(true)} apiAccessEnabled={apiAccessEnabled} />
+          ) : activeTab === 'diff' && hasMultipleVersions ? (
+            <div className="flex h-full min-h-0 flex-col overflow-hidden">
+              <div className="mb-4 flex flex-shrink-0 flex-col gap-3 rounded-lg border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-content-hover)/0.45)] p-3 sm:flex-row sm:items-end sm:justify-between">
+                <div className="grid flex-1 grid-cols-1 gap-3 sm:grid-cols-2">
+                  <label className="flex flex-col gap-1.5">
+                    <span className="text-[11px] font-medium uppercase tracking-[0.14em] text-[rgb(var(--ec-page-text-muted))]">
+                      From
+                    </span>
+                    <select
+                      value={diffFromVersion}
+                      onChange={(event) => setDiffFromVersion(event.target.value)}
+                      className="h-9 rounded-md border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-sm font-mono tabular-nums text-[rgb(var(--ec-page-text))] outline-hidden transition-colors focus:border-[rgb(var(--ec-accent))] focus:ring-1 focus:ring-[rgb(var(--ec-accent)/0.3)]"
+                    >
+                      {uniqueAvailableVersions.map((version) => (
+                        <option key={`from-${version.data.version}`} value={version.data.version}>
+                          v{version.data.version}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                  <label className="flex flex-col gap-1.5">
+                    <span className="text-[11px] font-medium uppercase tracking-[0.14em] text-[rgb(var(--ec-page-text-muted))]">
+                      To
+                    </span>
+                    <select
+                      value={diffToVersion}
+                      onChange={(event) => setDiffToVersion(event.target.value)}
+                      className="h-9 rounded-md border border-[rgb(var(--ec-dropdown-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-sm font-mono tabular-nums text-[rgb(var(--ec-page-text))] outline-hidden transition-colors focus:border-[rgb(var(--ec-accent))] focus:ring-1 focus:ring-[rgb(var(--ec-accent)/0.3)]"
+                    >
+                      {uniqueAvailableVersions.map((version) => (
+                        <option key={`to-${version.data.version}`} value={version.data.version}>
+                          v{version.data.version}
+                        </option>
+                      ))}
+                    </select>
+                  </label>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => setIsDiffModalOpen(true)}
+                  disabled={!selectedDiff}
+                  className="inline-flex h-9 items-center justify-center gap-1.5 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-dropdown-bg))] px-3 text-xs font-medium text-[rgb(var(--ec-page-text-muted))] transition-colors hover:bg-[rgb(var(--ec-content-hover))] hover:text-[rgb(var(--ec-page-text))] disabled:cursor-not-allowed disabled:opacity-50"
+                >
+                  <ArrowTopRightOnSquareIcon className="h-3.5 w-3.5" />
+                  Expand
+                </button>
+              </div>
+              <div className="min-h-0 flex-1 overflow-hidden">
+                {diffFromVersion === diffToVersion ? (
+                  <div className="flex h-full items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                    <p className="text-sm">Select two different versions</p>
+                  </div>
+                ) : !hasDiffFromContent || !hasDiffToContent ? (
+                  <div className="flex h-full items-center justify-center text-[rgb(var(--ec-page-text-muted))]">
+                    <p className="text-sm">No schema content available</p>
+                  </div>
+                ) : (
+                  <DiffViewer diffs={selectedDiffs} apiAccessEnabled={apiAccessEnabled} />
+                )}
+              </div>
+            </div>
           ) : (
             <SchemaContentViewer
               message={message}
@@ -507,7 +593,7 @@ export default function SchemaDetailsPanel({
       <VersionHistoryModal
         isOpen={isDiffModalOpen}
         onOpenChange={setIsDiffModalOpen}
-        diffs={allDiffs}
+        diffs={selectedDiffs}
         messageName={message.data.name}
         apiAccessEnabled={apiAccessEnabled}
       />

package/eventcatalog/src/components/SchemaExplorer/VersionHistoryModal.tsx

@@ -28,7 +28,7 @@ export default function VersionHistoryModal({
             <div className="flex items-center gap-3">
               <ArrowsPointingOutIcon className="h-6 w-6 text-[rgb(var(--ec-icon-color))]" />
               <div>
-                <Dialog.Title className="text-xl font-semibold text-[rgb(var(--ec-page-text))]">Version History</Dialog.Title>
+                <Dialog.Title className="text-xl font-semibold text-[rgb(var(--ec-page-text))]">Version Comparison</Dialog.Title>
                 <Dialog.Description className="text-sm text-[rgb(var(--ec-page-text-muted))] mt-1">
                   {messageName}
                 </Dialog.Description>
@@ -51,7 +51,7 @@ export default function VersionHistoryModal({
               <DiffViewer diffs={diffs} apiAccessEnabled={apiAccessEnabled} />
             ) : (
               <div className="flex items-center justify-center h-full">
-                <p className="text-[rgb(var(--ec-page-text-muted))] text-center">No version history available</p>
+                <p className="text-[rgb(var(--ec-page-text-muted))] text-center">No version comparison available</p>
               </div>
             )}
           </div>

package/eventcatalog/src/components/SchemaExplorer/types.ts

@@ -45,9 +45,9 @@ export interface SchemaItem {
 }
 
 export interface VersionDiff {
-  newerVersion: string;
-  olderVersion: string;
+  fromVersion: string;
+  toVersion: string;
   diffHtml: string;
-  newerContent: string;
-  olderContent: string;
+  fromContent: string;
+  toContent: string;
 }

package/eventcatalog/src/enterprise/custom-pages/routes.ts

@@ -0,0 +1,142 @@
+/**
+ * Licensed under the EventCatalog Commercial License.
+ * See /packages/core/eventcatalog/src/enterprise/LICENSE
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export interface CustomPageRoute {
+  /** Route pattern including the configured prefix, e.g. /custom/reports/[id] */
+  pattern: string;
+  /** File path relative to the custom pages directory */
+  file: string;
+  type: 'page' | 'endpoint';
+}
+
+export const DEFAULT_CUSTOM_PAGES_PREFIX = 'custom';
+
+/**
+ * Tracks the routable files during dev so route injection re-runs when files
+ * are added or removed. Never a route itself.
+ */
+export const CUSTOM_PAGES_MANIFEST_FILENAME = '.routes-manifest.json';
+
+const CUSTOM_PAGE_EXTENSIONS = /\.(astro|ts|js|mjs|json)$/i;
+
+/**
+ * Top-level route segments owned by EventCatalog. The custom pages prefix
+ * cannot start with any of these — everything else is collision-free because
+ * all user routes live under the prefix.
+ */
+const RESERVED_PREFIXES = [
+  'api',
+  'api-catalog',
+  'architecture',
+  'auth',
+  'diagrams',
+  'directory',
+  'discover',
+  'docs',
+  'icepanel',
+  'miro',
+  'rss',
+  'schemas',
+  'settings',
+  'studio',
+  'unauthorized',
+  'visualiser',
+  '.well-known',
+];
+
+/**
+ * Normalizes and validates the configured prefix (e.g. 'custom', 'internal/tools').
+ * Throws when the prefix is empty, contains unsafe characters or shadows a core route.
+ */
+export const resolveCustomPagesPrefix = (prefix: string | undefined): string => {
+  const normalized = (prefix ?? DEFAULT_CUSTOM_PAGES_PREFIX).replace(/^\/+|\/+$/g, '');
+
+  if (normalized.length === 0) {
+    throw new Error('[EventCatalog] pages.prefix cannot be empty.');
+  }
+
+  if (!/^[a-zA-Z0-9-_]+(\/[a-zA-Z0-9-_]+)*$/.test(normalized)) {
+    throw new Error(
+      `[EventCatalog] pages.prefix "${prefix}" is invalid. Use URL-safe characters (letters, numbers, - and _), optionally separated by "/".`
+    );
+  }
+
+  const firstSegment = normalized.split('/')[0].toLowerCase();
+  if (RESERVED_PREFIXES.includes(firstSegment)) {
+    throw new Error(`[EventCatalog] pages.prefix "${prefix}" is reserved by EventCatalog. Choose a different prefix.`);
+  }
+
+  return normalized;
+};
+
+/**
+ * Derives an Astro route pattern from a file path relative to the custom pages
+ * directory. Dynamic segments ([id], [...slug]) pass through untouched.
+ */
+export const deriveRoutePattern = (relativeFilePath: string, prefix: string): string => {
+  const withoutExtension = relativeFilePath.replace(CUSTOM_PAGE_EXTENSIONS, '');
+  const segments = withoutExtension.split(/[\\/]/).filter(Boolean);
+
+  if (segments[segments.length - 1] === 'index') {
+    segments.pop();
+  }
+
+  return `/${[prefix, ...segments].join('/')}`;
+};
+
+const walkDirectory = (directory: string, relativeTo: string): string[] => {
+  const files: string[] = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const fullPath = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...walkDirectory(fullPath, relativeTo));
+    } else if (entry.isFile()) {
+      files.push(path.relative(relativeTo, fullPath));
+    }
+  }
+
+  return files;
+};
+
+/**
+ * Lists the routable code files in the custom pages directory (sorted, relative paths).
+ * Underscore-prefixed files and directories follow the Astro convention: they are
+ * never routable (partials, helpers, colocated components).
+ */
+export const listCustomPageFiles = (customPagesDir: string): string[] => {
+  if (!fs.existsSync(customPagesDir)) return [];
+
+  return walkDirectory(customPagesDir, customPagesDir)
+    .filter((file) => CUSTOM_PAGE_EXTENSIONS.test(file))
+    .filter((file) => file !== CUSTOM_PAGES_MANIFEST_FILENAME)
+    .filter((file) => !file.split(path.sep).some((segment) => segment.startsWith('_')))
+    .sort();
+};
+
+/**
+ * Reads the custom pages directory and returns the routes to inject.
+ */
+export const getCustomPageRoutes = (customPagesDir: string, prefix: string): CustomPageRoute[] => {
+  const routes: CustomPageRoute[] = [];
+
+  for (const file of listCustomPageFiles(customPagesDir)) {
+    // pages/homepage.astro is the custom landing page, rendered by src/pages/index.astro
+    if (file === 'homepage.astro') continue;
+
+    routes.push({
+      pattern: deriveRoutePattern(file, prefix),
+      file,
+      type: file.toLowerCase().endsWith('.astro') ? 'page' : 'endpoint',
+    });
+  }
+
+  return routes;
+};
+
+export const isApiRoute = (route: CustomPageRoute): boolean => route.file.split(path.sep)[0] === 'api';

package/eventcatalog/src/enterprise/feature.ts

@@ -53,6 +53,9 @@ export const isEventCatalogUpgradeEnabled = () => !isEventCatalogStarterEnabled(
 // Custom landing pages are always enabled now.
 export const isCustomLandingPageEnabled = () => true;
 
+// User-defined pages and API routes (pages/*.astro, pages/api/*.ts)
+export const isCustomPagesEnabled = () => isEventCatalogScaleEnabled();
+
 export const isAuthEnabled = () => {
   const isAuthEnabledInCatalog = config?.auth?.enabled ?? false;
   const directory = process.env.PROJECT_DIR || process.cwd();

package/eventcatalog/src/enterprise/integrations/eventcatalog-features.ts

@@ -4,23 +4,80 @@
  */
 
 import type { AstroIntegration } from 'astro';
+import fs from 'node:fs';
 import path from 'path';
 import config from '../../../eventcatalog.config.js';
 import {
   isEventCatalogChatEnabled,
   isAuthEnabled,
   isEventCatalogScaleEnabled,
-  isEventCatalogStarterEnabled,
   isEventCatalogMCPEnabled,
   isEventCatalogMCPAuthEnabled,
   isFullCatalogAPIEnabled,
   isDevMode,
   isIntegrationsEnabled,
   isCustomDocsEnabled,
+  isCustomPagesEnabled,
   isSSR,
 } from '../../utils/feature';
+import {
+  CUSTOM_PAGES_MANIFEST_FILENAME,
+  getCustomPageRoutes,
+  isApiRoute,
+  listCustomPageFiles,
+  resolveCustomPagesPrefix,
+} from '../custom-pages/routes';
 
 const catalogDirectory = process.env.CATALOG_DIR || process.cwd();
+const customPagesDirectory = path.join(catalogDirectory, 'src/custom-pages');
+
+// Routes are injected at astro:config:setup, so adding or removing a custom page
+// file needs a full Astro restart before its route exists. This manifest is
+// registered via addWatchFile — rewriting it with a changed file list triggers
+// that restart (a Vite-level server.restart() does NOT re-run route injection).
+const customPagesManifest = path.join(customPagesDirectory, CUSTOM_PAGES_MANIFEST_FILENAME);
+
+const writeCustomPagesManifest = () => {
+  const content = JSON.stringify(listCustomPageFiles(customPagesDirectory));
+
+  try {
+    if (fs.existsSync(customPagesManifest) && fs.readFileSync(customPagesManifest, 'utf-8') === content) {
+      return;
+    }
+
+    fs.mkdirSync(customPagesDirectory, { recursive: true });
+    fs.writeFileSync(customPagesManifest, content);
+  } catch (error: any) {
+    console.warn(`[EventCatalog] Could not update the custom pages manifest: ${error.message}`);
+  }
+};
+
+const configureCustomPages = (params: {
+  command: 'dev' | 'build' | 'preview' | 'sync';
+  injectRoute: (route: { pattern: string; entrypoint: string }) => void;
+}) => {
+  const prefix = resolveCustomPagesPrefix(config.pages?.prefix);
+  const routes = getCustomPageRoutes(customPagesDirectory, prefix);
+
+  const apiRoutes = routes.filter(isApiRoute);
+  if (apiRoutes.length > 0 && !isSSR()) {
+    const message = `Custom API routes (${apiRoutes.map((route) => `pages/${route.file}`).join(', ')}) require EventCatalog to run in server mode. Set output: 'server' in your eventcatalog.config.js or remove the pages/api directory.`;
+
+    // The dev server serves endpoints dynamically regardless of output mode,
+    // so only fail the build — but warn early during development.
+    if (params.command === 'build') {
+      throw new Error(`[EventCatalog] ${message}`);
+    }
+    console.warn(`[EventCatalog] ${message}`);
+  }
+
+  for (const route of routes) {
+    params.injectRoute({
+      pattern: route.pattern,
+      entrypoint: path.join(customPagesDirectory, route.file),
+    });
+  }
+};
 
 const configureAuthentication = (params: {
   injectRoute: (route: { pattern: string; entrypoint: string }) => void;
@@ -148,6 +205,18 @@ export default function eventCatalogIntegration(): AstroIntegration {
           });
         }
 
+        // User-defined pages and API routes (Scale plan)
+        if (isCustomPagesEnabled()) {
+          configureCustomPages(params);
+        } else if (listCustomPageFiles(customPagesDirectory).length > 0) {
+          console.warn('[EventCatalog] Custom pages require the Scale plan. The routes for your pages will not be served.');
+        }
+
+        // Keep routes in sync during dev — a manifest change restarts the dev
+        // server so injectRoute runs again with the new file list
+        writeCustomPagesManifest();
+        params.addWatchFile(customPagesManifest);
+
         // Warn if integrations are configured without Scale plan
         if (config.integrations && !isIntegrationsEnabled()) {
           console.warn('[EventCatalog] Integrations require the Scale plan. Analytics integrations will not be loaded.');
@@ -165,6 +234,20 @@ export default function eventCatalogIntegration(): AstroIntegration {
           });
         }
       },
+      'astro:server:setup': ({ server }) => {
+        // When custom page files appear or disappear, refresh the manifest.
+        // A content change restarts the dev server (via addWatchFile above),
+        // which re-runs route injection. Unchanged content writes nothing,
+        // so events from the watcher's initial scan are no-ops.
+        const onCustomPageChange = (file: string) => {
+          if (!path.resolve(file).startsWith(customPagesDirectory + path.sep)) return;
+          if (!/\.(astro|ts|js|mjs)$/i.test(file)) return;
+          writeCustomPagesManifest();
+        };
+
+        server.watcher.on('add', onCustomPageChange);
+        server.watcher.on('unlink', onCustomPageChange);
+      },
     },
   };
 }

package/eventcatalog/src/pages/index.astro

@@ -21,7 +21,7 @@ const props = Astro.props;
 const pathToUserDefinedLandingPage = path.join(process.env.PROJECT_DIR || '', 'pages/homepage.astro');
 
 if (existsSync(pathToUserDefinedLandingPage) && isCustomLandingPageEnabled()) {
-  const customPages = import.meta.glob('/**/homepage.astro', { eager: true });
+  const customPages = import.meta.glob('/src/custom-pages/homepage.astro', { eager: true });
   // @ts-ignore
   CustomContent = Object.values(customPages)[0]?.default || null;
 

package/eventcatalog/src/toolkit/layouts/Layout.astro

@@ -0,0 +1,25 @@
+---
+/**
+ * Public layout shell for user-defined custom pages, imported by catalog
+ * authors as `@catalog/layouts/Layout.astro`.
+ *
+ * The props here are a documented, stable interface — internal layouts can
+ * change freely, this contract cannot.
+ */
+interface Props {
+  title: string;
+  description?: string;
+  /** Render the resource sidebar (domains, services, messages). Defaults to true. */
+  sidebar?: boolean;
+  /** Show the EventCatalog header (search, navigation). Defaults to true. */
+  showHeader?: boolean;
+}
+
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+
+const { title, description, sidebar = true, showHeader = true } = Astro.props;
+---
+
+<VerticalSideBarLayout title={title} description={description} showHeader={showHeader} showNestedSideBar={sidebar}>
+  <slot />
+</VerticalSideBarLayout>

package/eventcatalog/src/toolkit/utils/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Public utilities for user-defined custom pages, imported by catalog
+ * authors as `@catalog/utils`.
+ *
+ * These re-exports are a documented, stable interface — internal utils can
+ * change freely, this contract cannot. Getters return hydrated, cached
+ * collection entries (pass { getAllVersions: false } for latest versions only).
+ */
+export { getDomains } from '@utils/collections/domains';
+export { getServices } from '@utils/collections/services';
+export { getSystems } from '@utils/collections/systems';
+export { getEvents } from '@utils/collections/events';
+export { getCommands } from '@utils/collections/commands';
+export { getQueries } from '@utils/collections/queries';
+export { getFlows } from '@utils/collections/flows';
+export { getChannels } from '@utils/collections/channels';
+export { getEntities } from '@utils/collections/entities';
+export { getAgents } from '@utils/collections/agents';
+export { getContainers } from '@utils/collections/containers';
+export { getDataProducts } from '@utils/collections/data-products';
+export { getAdrs } from '@utils/collections/adrs';
+export { getTeams } from '@utils/collections/teams';
+export { getUsers } from '@utils/collections/users';
+
+// Resolve a specific version (semver) or the latest version of items in a collection
+export { getItemsFromCollectionByIdAndSemverOrLatest } from '@utils/collections/util';

package/eventcatalog/src/utils/feature.ts

@@ -25,6 +25,7 @@ export {
   isEventCatalogChatEnabled,
   isEventCatalogUpgradeEnabled,
   isCustomLandingPageEnabled,
+  isCustomPagesEnabled,
   isAuthEnabled,
   isCustomStylesEnabled,
   isEventCatalogMCPEnabled,