@eventcatalog/core 5.5.1 → 5.6.0

package/eventcatalog/src/features/mcp/apps/schema-viewer/view.tsx

@@ -12,6 +12,7 @@ import AvroSchemaViewer from '../../../../components/SchemaExplorer/AvroSchemaVi
 import ProtobufSchemaViewer from '../../../../components/SchemaExplorer/ProtobufSchemaViewer';
 import { SchemaCode } from './schema-code';
 import { RESOURCE_TYPE_LABELS } from '../shared/resource-types';
+import { fullscreenStyle } from '../shared/app-view';
 import type { SchemaViewerPayload, SchemaViewerSchema } from './shared';
 
 const INLINE_MAX_HEIGHT = '560px';
@@ -75,7 +76,7 @@ export function SchemaViewerView({ app, payload, hostContext }: SchemaViewerView
     'inline-flex h-7 items-center gap-1.5 rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-card-bg))] px-2.5 text-xs font-medium text-[rgb(var(--ec-page-text))] transition-colors hover:border-[rgb(var(--ec-accent))] hover:text-[rgb(var(--ec-accent))]';
 
   return (
-    <div className={`flex flex-col ${isFullscreen ? 'h-screen' : ''}`}>
+    <div className="flex flex-col" style={isFullscreen ? fullscreenStyle(hostContext) : undefined}>
       <div className="flex items-center justify-between gap-3 border-b border-[rgb(var(--ec-page-border))] px-3 py-2">
         <div className="flex min-w-0 items-center gap-2 text-[13px]">
           <span className="shrink-0 rounded bg-[rgb(var(--ec-accent-subtle))] px-1.5 py-px text-[10px] font-semibold uppercase tracking-wide text-[rgb(var(--ec-accent))]">

package/eventcatalog/src/features/mcp/apps/shared/app-view.tsx

@@ -2,7 +2,7 @@
  * Connecting the EventCatalog viewer MCP App to the host, loading the tool result's payload, following the
  * host's theme and display mode, and mounting the view.
  */
-import { useEffect, useState, type ComponentType } from 'react';
+import { useEffect, useState, type ComponentType, type CSSProperties } from 'react';
 import { config as configureZod } from 'zod';
 import { createRoot } from 'react-dom/client';
 import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
@@ -20,6 +20,24 @@ const applyTheme = (context?: McpUiHostContext) => {
   if (context?.theme) document.documentElement.setAttribute('data-theme', context.theme);
 };
 
+/**
+ * The view full screen: the height of the frame, kept clear of what the host draws over it on phones (the notch,
+ * the home indicator, the message box), which it reports as safe area insets
+ */
+export const fullscreenStyle = (context?: McpUiHostContext): CSSProperties => {
+  const insets = context?.safeAreaInsets;
+  return {
+    height: '100vh',
+    boxSizing: 'border-box',
+    ...(insets && {
+      paddingTop: insets.top,
+      paddingRight: insets.right,
+      paddingBottom: insets.bottom,
+      paddingLeft: insets.left,
+    }),
+  };
+};
+
 type McpAppViewOptions<Payload> = {
   name: string;
   /** Key of the payload in the model-facing tool result's `_meta` */
@@ -61,8 +79,9 @@ export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
     appInfo: { name: options.name, version: '1.0.0' },
     // The views fit inline and have a full screen button (the server asks hosts to open them full screen)
     capabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    // Listeners go on before the view connects: hosts send the tool's result as soon as it has
     onAppCreated: (createdApp) => {
-      createdApp.ontoolresult = (result) => {
+      createdApp.addEventListener('toolresult', (result) => {
         if (result.isError) {
           setError(result.content?.find((item) => item.type === 'text')?.text ?? options.loadErrorMessage);
           return;
@@ -70,11 +89,11 @@ export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
         loadPayload(createdApp, result, options)
           .then(setPayload)
           .catch((loadError) => setError(String(loadError?.message ?? loadError)));
-      };
-      createdApp.onhostcontextchanged = (context) => {
+      });
+      createdApp.addEventListener('hostcontextchanged', (context) => {
         applyTheme(context);
         setHostContext((previous) => ({ ...previous, ...context }));
-      };
+      });
     },
   });
 

package/eventcatalog/src/features/mcp/mcp-apps.ts

@@ -54,6 +54,8 @@ export type McpAppDefinition<Shape extends z.ZodRawShape, ViewShape extends z.Zo
     csp?: { resourceDomains?: string[]; connectDomains?: string[] };
     /** How hosts open the view: ChatGPT reads these before loading it, so it can open straight in that mode */
     displayModes?: { preferred: McpUiDisplayMode; available: McpUiDisplayMode[] };
+    /** Whether the host frames the view with a border and background (hosts' defaults differ, e.g. Claude's web and mobile apps) */
+    prefersBorder?: boolean;
   };
   /**
    * Ties every result to one view (ChatGPT's `openai/widgetSessionId`): the host updates the view it already
@@ -151,7 +153,10 @@ export function registerMcpApp<Shape extends z.ZodRawShape, ViewShape extends z.
         mimeType: RESOURCE_MIME_TYPE,
         text: await loadView(),
         _meta: {
-          ...(app.resource.csp && { ui: { csp: app.resource.csp } }),
+          ui: {
+            ...(app.resource.csp && { csp: app.resource.csp }),
+            ...(app.resource.prefersBorder !== undefined && { prefersBorder: app.resource.prefersBorder }),
+          },
           ...(app.resource.displayModes && {
             'openai/ui': {
               preferredDisplayMode: app.resource.displayModes.preferred,

package/eventcatalog/src/features/mcp/mcp-server.ts

@@ -512,6 +512,8 @@ function createMcpServer(
       csp: { resourceDomains: [catalogUrl] },
       // Diagrams and schemas need the room, so hosts that can open the viewer full screen straight away
       displayModes: { preferred: 'fullscreen', available: ['inline', 'fullscreen'] },
+      // The viewer has its own background: no frame around it, on the web and on phones alike
+      prefersBorder: false,
     },
     // One viewer per server: each result updates the viewer the host already shows
     sessionId: scope ? `eventcatalog:${scope.ref.kind}:${scope.ref.id}` : 'eventcatalog',

package/eventcatalog/src/features/studio/server/canvas-mcp.ts

@@ -124,6 +124,8 @@ export function registerCanvasTools(server: McpServer, { catalogUrl, userAgent }
       // The view joins the canvas over the collaboration WebSocket, and shows icons served by this EventCatalog
       csp: { connectDomains: [new URL(socketUrl).origin, catalogUrl], resourceDomains: [catalogUrl] },
       displayModes: { preferred: 'fullscreen', available: ['inline', 'fullscreen'] },
+      // The canvas has its own background: no frame around it, on the web and on phones alike
+      prefersBorder: false,
     },
     metaKey: CANVAS_META_KEY,
     tool: {

package/eventcatalog/src/features/studio/tool-sync.ts

@@ -6,7 +6,8 @@ import type { Status } from './hooks/use-studio-flow';
  * Syncing a canvas through MCP tool calls, for when a view can't open the collaboration WebSocket
  * (e.g. an MCP App inside a chat whose sandbox blocks it). Each call sends the server what it doesn't have
  * yet (by its state vector) and our presence, and gets back what we don't have and everyone's presence.
- * Slower than the WebSocket (it polls), but works wherever the chat can call the MCP server's tools.
+ * Slower than the WebSocket (it polls), but works wherever the chat can call the MCP server's tools. It polls less
+ * while nothing changes, and rarely while the view is out of sight (chats keep every view they showed running).
  */
 
 export type SyncRequest = {
@@ -33,6 +34,11 @@ export const fromBase64 = (text: string) => Uint8Array.from(atob(text), (char) =
 /** Applied with this origin, so undo (which tracks local changes) leaves other people's changes alone */
 const REMOTE = Symbol('tool-sync');
 
+/** Waiting longest between syncs while nothing changes on either side */
+const IDLE_INTERVAL_MS = 5000;
+/** Between syncs while the view is out of sight (slowed, not stopped: a host that wrongly reports it hidden still syncs) */
+const OUT_OF_SIGHT_INTERVAL_MS = 15_000;
+
 export function startToolSync(
   doc: Y.Doc,
   awareness: Awareness,
@@ -44,32 +50,90 @@ export function startToolSync(
   }: { canvasId: string; sync: ToolSync; onStatus: (status: Status) => void; intervalMs?: number }
 ) {
   let serverVector: Uint8Array | undefined;
+  let lastServerVector: string | undefined;
+  let lastAwareness: string | undefined;
   let stopped = false;
+  let syncing = false;
   let timer: ReturnType<typeof setTimeout> | undefined;
+  let dueAt = 0;
+  // Slower while nothing changes (a chat keeps every view it showed running, each polling), back to quick on a change
+  let delay = intervalMs;
+  // Hosts keep a chat's earlier views running: one scrolled out of sight, or in a hidden tab, syncs rarely
+  let inView = true;
+  const isShown = () => inView && document.visibilityState !== 'hidden';
+
+  const schedule = (ms: number) => {
+    clearTimeout(timer);
+    dueAt = Date.now() + ms;
+    timer = setTimeout(tick, ms);
+  };
 
   const tick = async () => {
+    timer = undefined;
+    if (stopped || syncing) return;
+    syncing = true;
     try {
+      const update = Y.encodeStateAsUpdate(doc, serverVector);
       const response = await sync({
         canvasId,
         clientId: doc.clientID,
         stateVector: toBase64(Y.encodeStateVector(doc)),
-        update: toBase64(Y.encodeStateAsUpdate(doc, serverVector)),
+        update: toBase64(update),
         awareness: toBase64(encodeAwarenessUpdate(awareness, [doc.clientID])),
       });
       if (stopped) return;
       Y.applyUpdate(doc, fromBase64(response.update), REMOTE);
       serverVector = fromBase64(response.stateVector);
       if (response.awareness) applyAwarenessUpdate(awareness, fromBase64(response.awareness), REMOTE);
+      // Anything new either way (the canvas, or anyone's presence) keeps it quick
+      const changed = response.stateVector !== lastServerVector || response.awareness !== lastAwareness;
+      lastServerVector = response.stateVector;
+      lastAwareness = response.awareness;
+      delay = changed ? intervalMs : Math.min(delay * 1.5, IDLE_INTERVAL_MS);
       onStatus('connected');
     } catch {
       if (!stopped) onStatus('disconnected');
+    } finally {
+      syncing = false;
     }
-    if (!stopped) timer = setTimeout(tick, intervalMs);
+    // Out of sight: rarely, and straight away again once it's shown (see show)
+    if (!stopped) schedule(isShown() ? delay : Math.max(delay, OUT_OF_SIGHT_INTERVAL_MS));
+  };
+
+  // Our own changes and presence go out within the quick interval, however long it's been waiting
+  const wake = (_update: unknown, origin: unknown) => {
+    if (origin === REMOTE || stopped) return;
+    delay = intervalMs;
+    if (timer && dueAt > Date.now() + intervalMs) schedule(intervalMs);
   };
+  doc.on('update', wake);
+  awareness.on('update', wake);
+
+  const show = () => {
+    if (stopped || !isShown() || syncing || dueAt <= Date.now() + intervalMs) return;
+    clearTimeout(timer);
+    delay = intervalMs;
+    void tick();
+  };
+  document.addEventListener('visibilitychange', show);
+  // Seen from inside the chat's frame: whether the view is on the screen at all
+  const observer =
+    typeof IntersectionObserver === 'undefined'
+      ? undefined
+      : new IntersectionObserver(([entry]) => {
+          inView = entry?.isIntersecting ?? true;
+          show();
+        });
+  observer?.observe(document.documentElement);
+
   void tick();
 
   return () => {
     stopped = true;
     clearTimeout(timer);
+    doc.off('update', wake);
+    awareness.off('update', wake);
+    document.removeEventListener('visibilitychange', show);
+    observer?.disconnect();
   };
 }

package/eventcatalog/src/features/tools/catalog-tools.ts

@@ -5,7 +5,12 @@
 import { getCollection } from 'astro:content';
 import { z } from 'zod';
 import { getSchemaFormatFromURL } from '@utils/collections/schemas';
-import { getItemsFromCollectionByIdAndSemverOrLatest, processSpecifications, versionMatches } from '@utils/collections/util';
+import {
+  getItemsFromCollectionByIdAndSemverOrLatest,
+  getSpecificationCodeLanguage,
+  processSpecifications,
+  versionMatches,
+} from '@utils/collections/util';
 import { getUbiquitousLanguageWithSubdomains } from '@utils/collections/domains';
 import { getAbsoluteFilePathForAstroFile } from '@utils/files';
 import fs from 'node:fs';
@@ -464,7 +469,7 @@ export async function getSchemaForResource(params: { resourceId: string; resourc
     ...processSpecifications(resource.data.specifications).map((spec) => ({
       name: spec.name,
       path: spec.path,
-      format: spec.type,
+      format: spec.type === 'generic' ? getSpecificationCodeLanguage(spec.path) : spec.type,
     })),
   ];
 
@@ -1332,7 +1337,7 @@ export const toolDescriptions = {
   getMessagesProducedOrConsumedByResource:
     'Use this tool to get the messages (events, commands, queries) a service, agent, domain or system sends and receives. Each message is resolved to its catalog id, version, name and summary; messages that are referenced but not documented in the catalog are marked notFound. For a domain or system, this includes what the services, agents, systems and subdomains inside it send and receive, and each message lists `by`: the resources that send or receive it (e.g. services/order-service). Omit the version to use the latest version of the resource.',
   getSchemaForResource:
-    'Use this tool to get the schema or specifications (openapi or asyncapi or graphql) for a resource by its id and version',
+    'Use this tool to get the schema or specifications (openapi, asyncapi, graphql or generic specifications such as XML, JSON or YAML files) for a resource by its id and version',
   findResourcesByOwner:
     'Use this tool to find all resources (agents, services, events, commands, etc.) owned by a specific team or user',
   getProducersOfMessage:

package/eventcatalog/src/pages/.well-known/api-catalog.ts

@@ -2,7 +2,7 @@ import type { APIRoute } from 'astro';
 import yaml from 'js-yaml';
 import { getServices, getSpecificationsForService } from '@utils/collections/services';
 import { getDomains, getSpecificationsForDomain } from '@utils/collections/domains';
-import type { ProcessedSpecification } from '@utils/collections/util';
+import { getSpecificationMediaType, type ProcessedSpecification } from '@utils/collections/util';
 import { buildUrl } from '@utils/url-builder';
 import { readResourceFile } from '@utils/resource-files';
 import { isEventCatalogMCPEnabled } from '@utils/feature';
@@ -26,16 +26,6 @@ type ApiCatalogResource = Awaited<ReturnType<typeof getServices>>[number] | Awai
 
 const absoluteUrl = (request: Request, pathOrUrl: string) => new URL(pathOrUrl, request.url).toString();
 
-const getSpecificationMediaType = (specification: ProcessedSpecification) => {
-  const extension = specification.filename.split('.').pop()?.toLowerCase();
-
-  if (specification.type === 'graphql') return 'application/graphql';
-  if (extension === 'json') return 'application/json';
-  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
-
-  return 'text/plain';
-};
-
 const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
   return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
 };

package/eventcatalog/src/pages/api-catalog/specifications/[collection]/[id]/[version]/[specification].ts

@@ -2,7 +2,7 @@ import type { APIRoute } from 'astro';
 import { getCollection } from 'astro:content';
 import { getSpecificationsForDomain } from '@utils/collections/domains';
 import { getSpecificationsForService } from '@utils/collections/services';
-import type { ProcessedSpecification } from '@utils/collections/util';
+import { getSpecificationMediaType, type ProcessedSpecification } from '@utils/collections/util';
 import { readResourceFile } from '@utils/resource-files';
 
 type SupportedCollection = 'domains' | 'services';
@@ -11,16 +11,6 @@ const isSupportedCollection = (collection: string | undefined): collection is Su
   return collection === 'domains' || collection === 'services';
 };
 
-const getSpecificationMediaType = (specification: ProcessedSpecification) => {
-  const extension = specification.filename.split('.').pop()?.toLowerCase();
-
-  if (specification.type === 'graphql') return 'application/graphql';
-  if (extension === 'json') return 'application/json';
-  if (extension === 'yaml' || extension === 'yml') return 'application/yaml';
-
-  return 'text/plain';
-};
-
 const getSpecificationIdentifier = (specification: ProcessedSpecification) => {
   return `${specification.type}-${Buffer.from(specification.path).toString('base64url')}`;
 };

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/generic/[filename].astro

@@ -0,0 +1,137 @@
+---
+import VerticalSideBarLayout from '@layouts/VerticalSideBarLayout.astro';
+import Footer from '@layouts/Footer.astro';
+import { Page } from './_[filename].data';
+import SpecificationSource from './_SpecificationSource';
+import { buildUrl } from '@utils/url-builder';
+import { getGenericSpecificationIcon, resolveIconUrl } from '@utils/icon';
+import { readResourceFile, resourceFileExists } from '@utils/resource-files';
+import { resolveHeaders } from '@utils/remote-spec';
+import Admonition from '@components/MDX/Admonition';
+import NewVersionBanner from '@components/NewVersionBanner.astro';
+import Badge from '@components/Badge.astro';
+import { getResourceTypeBadge } from '@utils/collections/resource-type-badge';
+import { getResourceNoun, getSpecificationCodeLanguage } from '@utils/collections/util';
+
+export const prerender = Page.prerender;
+export const getStaticPaths = Page.getStaticPaths;
+
+// Get data
+const pageData = await Page.getData(Astro);
+if (!pageData) return Astro.rewrite('/404');
+const {
+  collection,
+  data,
+  filename,
+  filenameWithoutExtension,
+  path: relativeSpecPath,
+  specificationName,
+  icon,
+  headers = {},
+} = pageData;
+
+// Generic specifications are shown as source, without parsing them
+const isRemote = /^https?:\/\//i.test(relativeSpecPath);
+let fileExists = isRemote || resourceFileExists(pageData, relativeSpecPath);
+let content = '';
+
+if (isRemote) {
+  // A remote file that can't be fetched is shown as not found, like a missing local file, so it doesn't fail the build
+  const response = await fetch(relativeSpecPath, { headers: resolveHeaders(headers) }).catch(() => null);
+
+  if (response?.ok) {
+    content = await response.text();
+  } else {
+    fileExists = false;
+    console.warn(`Failed to fetch specification ${relativeSpecPath}: ${response ? response.status : 'network error'}`);
+  }
+} else if (fileExists) {
+  content = readResourceFile(pageData, relativeSpecPath) ?? '';
+}
+
+const iconURL = resolveIconUrl(getGenericSpecificationIcon(icon));
+
+// Create comprehensive page title
+const pageTitle = `${collection} | ${data.name} | ${specificationName}`.replace(/^\w/, (c) => c.toUpperCase());
+
+const badges = [
+  getResourceTypeBadge(collection),
+  {
+    textColor: 'gray',
+    content: specificationName,
+    iconURL,
+    id: 'generic-specification-badge',
+  },
+];
+
+// Index only the latest version
+const pagefindAttributes =
+  data.version === data.latestVersion
+    ? {
+        'data-pagefind-body': '',
+        'data-pagefind-meta': `title:${pageTitle}`,
+      }
+    : {};
+---
+
+<VerticalSideBarLayout title={pageTitle} description={`${specificationName} for ${data.name}`}>
+  <main class="flex docs-layout min-h-full bg-[rgb(var(--ec-page-bg))]" {...pagefindAttributes}>
+    <div class="flex docs-layout w-full">
+      <div class="w-full min-w-0 lg:mr-2 xl:pr-12 py-8 bg-[rgb(var(--ec-page-bg))]">
+        <!-- Title and subtitle sized like the resource's overview page, kept compact so the source starts high up -->
+        <div class="border-b border-[rgb(var(--ec-page-border))] pb-4">
+          <h1 class="text-2xl md:text-4xl font-bold text-[rgb(var(--ec-page-text))]">{data.name}</h1>
+          <p class="text-base pt-2 text-[rgb(var(--ec-page-text-muted))] font-light">{specificationName}</p>
+          <div class="flex flex-wrap gap-1.5 pt-3">
+            {badges.map((badge: any) => <Badge badge={badge} />)}
+          </div>
+        </div>
+
+        <div data-pagefind-ignore>
+          {
+            data.version !== data.latestVersion && (
+              <NewVersionBanner
+                subject={getResourceNoun(collection)}
+                name={data.name}
+                latestOf={specificationName}
+                latestVersion={data.latestVersion}
+                href={buildUrl(`/docs/${collection}/${data.id}/${data.latestVersion}/generic/${filenameWithoutExtension}`)}
+              />
+            )
+          }
+        </div>
+
+        {
+          !fileExists && (
+            <Admonition type="warning" title="Specification not found">
+              <p>The specification file could not be found at {relativeSpecPath}.</p>
+            </Admonition>
+          )
+        }
+
+        {
+          fileExists && (
+            <div class="mt-4 not-prose">
+              <SpecificationSource
+                client:load
+                name={`${data.name} - ${specificationName}`}
+                version={data.version}
+                code={content}
+                language={getSpecificationCodeLanguage(filename)}
+              />
+            </div>
+          )
+        }
+
+        <Footer />
+      </div>
+    </div>
+  </main>
+
+  <style is:global>
+    .docs-layout .prose {
+      max-width: none;
+      overflow: auto;
+    }
+  </style>
+</VerticalSideBarLayout>

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/generic/_SpecificationSource.tsx

@@ -0,0 +1,44 @@
+import { useState } from 'react';
+import SchemaCodeBlock from '@components/SchemaExplorer/SchemaCodeBlock';
+import SchemaCodeModal from '@components/SchemaExplorer/SchemaCodeModal';
+import { copyToClipboard } from '@components/SchemaExplorer/utils';
+
+interface Props {
+  /** The specification's name, shown in fullscreen */
+  name: string;
+  version: string;
+  code: string;
+  /** The syntax to highlight: json, yaml, xml or text */
+  language: string;
+}
+
+/** A generic specification's source, in the same code box as the Schema Explorer */
+export default function SpecificationSource({ name, version, code, language }: Props) {
+  const [isCopied, setIsCopied] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+
+  const onCopy = async () => {
+    if (!(await copyToClipboard(code))) return;
+    setIsCopied(true);
+    setTimeout(() => setIsCopied(false), 2000);
+  };
+
+  return (
+    <>
+      <SchemaCodeBlock
+        code={code}
+        extension={language}
+        onCopy={onCopy}
+        isCopied={isCopied}
+        onOpenFullscreen={() => setIsFullscreen(true)}
+      />
+      <SchemaCodeModal
+        isOpen={isFullscreen}
+        onOpenChange={setIsFullscreen}
+        message={{ data: { name, version }, schemaExtension: language, schemaContent: code }}
+        onCopy={onCopy}
+        isCopied={isCopied}
+      />
+    </>
+  );
+}

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/generic/_[filename].data.ts

@@ -0,0 +1,75 @@
+// pages/docs/[type]/[id]/[version]/generic/[filename].astro
+import { isSSR } from '@utils/feature';
+import { HybridPage } from '@utils/page-loaders/hybrid-page';
+import type { CollectionEntry } from 'astro:content';
+import type { CollectionTypes, PageTypes } from '@types';
+import type { ProcessedSpecification } from '@utils/collections/util';
+
+const toPageProps = (type: PageTypes, spec: ProcessedSpecification, item: CollectionEntry<CollectionTypes>) => ({
+  type,
+  filenameWithoutExtension: spec.filenameWithoutExtension || spec.type,
+  filename: spec.filename || spec.type,
+  path: spec.path,
+  specificationName: spec.name,
+  icon: spec.icon,
+  headers: spec.headers,
+  ...item,
+});
+
+export class Page extends HybridPage {
+  static get prerender(): boolean {
+    return !isSSR();
+  }
+
+  static async getStaticPaths(): Promise<Array<{ params: any; props: any }>> {
+    if (isSSR()) {
+      return [];
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+    const { getSpecificationsForService } = await import('@utils/collections/services');
+
+    const itemTypes: PageTypes[] = ['events', 'commands', 'queries', 'services', 'domains'];
+    const allItems = await Promise.all(itemTypes.map((type) => pageDataLoader[type]()));
+
+    return allItems.flatMap((items, index) =>
+      items.flatMap((item) =>
+        getSpecificationsForService(item)
+          .filter((spec) => spec.type === 'generic')
+          .map((spec) => ({
+            params: {
+              type: itemTypes[index],
+              id: item.data.id,
+              version: item.data.version,
+              filename: spec.filenameWithoutExtension || spec.type,
+            },
+            props: toPageProps(itemTypes[index], spec, item),
+          }))
+      )
+    );
+  }
+
+  protected static async fetchData(params: any) {
+    const { type, id, version, filename } = params;
+
+    if (!type || !id || !version || !filename) {
+      return null;
+    }
+
+    const { pageDataLoader } = await import('@utils/page-loaders/page-data-loader');
+    const { getSpecificationsForService } = await import('@utils/collections/services');
+
+    const items = await pageDataLoader[type as PageTypes]();
+    const item = items.find((i) => i.data.id === id && i.data.version === version);
+
+    if (!item) {
+      return null;
+    }
+
+    const spec = getSpecificationsForService(item).find(
+      (s) => s.type === 'generic' && (s.filenameWithoutExtension || s.type) === filename
+    );
+
+    return spec ? toPageProps(type, spec, item) : null;
+  }
+}

package/eventcatalog/src/pages/docs/[type]/[id]/[version]/index.astro

@@ -65,7 +65,7 @@ import {
 import { getSchemasFromResource } from '@utils/collections/schemas';
 import { getIcon } from '@utils/badges';
 import { buildUrl, buildEditUrlForResource } from '@utils/url-builder';
-import { isIconPath, resolveIconUrl } from '@utils/icon';
+import { getGenericSpecificationIcon, isIconPath, resolveIconUrl } from '@utils/icon';
 import {
   isEventCatalogChatVisible,
   isMarkdownDownloadEnabled,
@@ -249,6 +249,7 @@ const getSpecificationBadges = () => {
   const asyncapiSpecs = specifications.filter((spec) => spec.type === 'asyncapi');
   const openapiSpecs = specifications.filter((spec) => spec.type === 'openapi');
   const graphQLSpecs = specifications.filter((spec) => spec.type === 'graphql');
+  const genericSpecs = specifications.filter((spec) => spec.type === 'generic');
 
   if (openapiSpecs.length > 0) {
     for (const spec of openapiSpecs) {
@@ -290,6 +291,18 @@ const getSpecificationBadges = () => {
     }
   }
 
+  for (const spec of genericSpecs) {
+    badges.push({
+      content: spec.name,
+      iconURL: resolveIconUrl(getGenericSpecificationIcon(spec.icon)),
+      class: 'text-[rgb(var(--ec-page-text))] hover:underline',
+      id: 'generic-specification-badge',
+      url: buildUrl(
+        `/docs/${props.collection}/${props.data.id}/${props.data.version}/generic/${spec.filenameWithoutExtension}`
+      ),
+    });
+  }
+
   return badges;
 };
 

package/eventcatalog/src/stores/sidebar-store/builders/domain.ts

@@ -16,7 +16,7 @@ import {
 import { isVisualiserEnabled, isChangelogEnabled } from '@utils/feature';
 import { pluralizeMessageType } from '@utils/collections/messages';
 import { getSpecificationsForDomain, hasUbiquitousLanguageTermsWithSubdomainsInCollection } from '@utils/collections/domains';
-import { customIconFieldsForResource } from '@utils/icon';
+import { customIconFieldsForResource, getGenericSpecificationIcon } from '@utils/icon';
 import { resolveSidebarPages, toCustomSidebarContext, type SidebarSpec } from '../custom-sidebar';
 
 // Sort resolved collection entries A-Z by their display name (falling back to id).
@@ -143,6 +143,7 @@ export const buildDomainSections = (
   const openAPISpecifications = specifications.filter((specification) => specification.type === 'openapi');
   const asyncAPISpecifications = specifications.filter((specification) => specification.type === 'asyncapi');
   const graphQLSpecifications = specifications.filter((specification) => specification.type === 'graphql');
+  const genericSpecifications = specifications.filter((specification) => specification.type === 'generic');
   const renderSpecifications = hasSpecifications && shouldRenderSideBarSection(domain, 'specifications');
 
   // Resource subsections. These are built once and shared between the "Resources"
@@ -284,6 +285,14 @@ export const buildDomainSections = (
                 `/docs/domains/${domain.data.id}/${domain.data.version}/graphql/${specification.filenameWithoutExtension}`
               ),
             })),
+            ...genericSpecifications.map((specification) => ({
+              type: 'item',
+              title: specification.name,
+              leftIcon: getGenericSpecificationIcon(specification.icon),
+              href: buildUrl(
+                `/docs/domains/${domain.data.id}/${domain.data.version}/generic/${specification.filenameWithoutExtension}`
+              ),
+            })),
           ] as ChildRef[],
         }
       : null,