@eventcatalog/core 4.12.2 → 5.0.0-beta.0

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

@@ -0,0 +1,10 @@
+/**
+ * Stands in for `mermaid` in MCP App views. The visualiser's optional Mermaid view loads it
+ * lazily, but MCP hosts already get the diagram as Mermaid text, and mermaid would more than
+ * double the size of the view's HTML.
+ */
+const unavailable = async () => {
+  throw new Error('The Mermaid view is not available here');
+};
+
+export default { initialize: () => {}, render: unavailable, parse: unavailable };

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

@@ -0,0 +1,65 @@
+/**
+ * The schema's source, highlighted like the Schema tab on EventCatalog's schema pages.
+ * Uses the light build of the highlighter with only the languages schemas are written in, to keep the view small
+ * (languages it doesn't have, such as TypeScript, are shown without highlighting).
+ */
+import { useState } from 'react';
+import { PrismLight as SyntaxHighlighter } from 'react-syntax-highlighter';
+import json from 'react-syntax-highlighter/dist/esm/languages/prism/json';
+import protobuf from 'react-syntax-highlighter/dist/esm/languages/prism/protobuf';
+import yaml from 'react-syntax-highlighter/dist/esm/languages/prism/yaml';
+import markup from 'react-syntax-highlighter/dist/esm/languages/prism/markup';
+import graphql from 'react-syntax-highlighter/dist/esm/languages/prism/graphql';
+import oneDark from 'react-syntax-highlighter/dist/esm/styles/prism/one-dark';
+import oneLight from 'react-syntax-highlighter/dist/esm/styles/prism/one-light';
+import { Check, Copy } from 'lucide-react';
+import { copyToClipboard } from '@utils/clipboard';
+import { SCHEMA_CODE_STYLE } from '../../../../components/SchemaExplorer/utils';
+
+SyntaxHighlighter.registerLanguage('json', json);
+SyntaxHighlighter.registerLanguage('protobuf', protobuf);
+SyntaxHighlighter.registerLanguage('yaml', yaml);
+SyntaxHighlighter.registerLanguage('xml', markup);
+SyntaxHighlighter.registerLanguage('graphql', graphql);
+
+type SchemaCodeProps = {
+  code: string;
+  /** Language to highlight the code in, from the server (see getLanguageForHighlight) */
+  language: string;
+  isDark: boolean;
+  /** Grows with the code up to this height; fills its container when not set */
+  maxHeight?: string;
+};
+
+export function SchemaCode({ code, language, isDark, maxHeight }: SchemaCodeProps) {
+  const [copyState, setCopyState] = useState<'idle' | 'copied' | 'failed'>('idle');
+
+  const copy = async () => {
+    setCopyState((await copyToClipboard(code)) ? 'copied' : 'failed');
+    setTimeout(() => setCopyState('idle'), 2000);
+  };
+
+  return (
+    <div
+      className={`relative overflow-hidden rounded-md border border-[rgb(var(--ec-page-border))] bg-[rgb(var(--ec-code-bg,var(--ec-card-bg)))] ${maxHeight ? '' : 'h-full'}`}
+    >
+      <button
+        type="button"
+        onClick={copy}
+        className="absolute right-3 top-3 z-10 inline-flex items-center gap-1 rounded-md bg-[rgb(var(--ec-content-hover)/0.9)] px-2 py-1.5 text-[11px] font-medium text-[rgb(var(--ec-page-text-muted))] backdrop-blur-xs transition-colors hover:text-[rgb(var(--ec-page-text))]"
+      >
+        {copyState === 'copied' ? <Check aria-hidden className="h-3 w-3" /> : <Copy aria-hidden className="h-3 w-3" />}
+        {copyState === 'copied' ? 'Copied!' : copyState === 'failed' ? 'Could not copy' : 'Copy'}
+      </button>
+      <SyntaxHighlighter
+        language={language}
+        style={isDark ? oneDark : oneLight}
+        customStyle={{ ...SCHEMA_CODE_STYLE, ...(maxHeight ? { maxHeight } : { height: '100%' }) }}
+        showLineNumbers
+        wrapLongLines
+      >
+        {code}
+      </SyntaxHighlighter>
+    </div>
+  );
+}

package/eventcatalog/src/features/mcp/apps/schema-viewer/shared.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared by the MCP server and the schema viewer MCP App view (view.tsx, shown by the viewer in ../viewer).
+ * Kept free of server-only imports so it can be bundled into the view.
+ */
+import type { ViewableSchema } from '@components/SchemaExplorer/parse-schema';
+
+export type SchemaViewerSchema = ViewableSchema & {
+  /** Set when a message has more than one schema */
+  name?: string;
+  format: string;
+  /** Language to highlight the code in (see getLanguageForHighlight) */
+  language: string;
+  code: string;
+};
+
+export type SchemaViewerPayload = {
+  resource: { collection: string; id: string; version: string; name: string };
+  /** The EventCatalog the schema came from, for links back to it */
+  catalogUrl: string;
+  /** Path of the resource's page in EventCatalog */
+  docsPath: string;
+  schemas: SchemaViewerSchema[];
+};

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

@@ -0,0 +1,170 @@
+/**
+ * The schema, shown by the EventCatalog viewer MCP App (../viewer) for showResource with view "schema".
+ * Like EventCatalog's schema pages, it shows a message's schema as its source (Schema) or with the Schema
+ * Explorer's viewers (Properties, for JSON Schema, Avro and Protobuf), in MCP hosts that support MCP Apps.
+ * Hosts without MCP Apps support show the tool's text instead.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+import { Code, ExternalLink, Maximize2, Minimize2, Table } from 'lucide-react';
+import JSONSchemaViewer from '../../../../components/SchemaExplorer/JSONSchemaViewer';
+import AvroSchemaViewer from '../../../../components/SchemaExplorer/AvroSchemaViewer';
+import ProtobufSchemaViewer from '../../../../components/SchemaExplorer/ProtobufSchemaViewer';
+import { SchemaCode } from './schema-code';
+import { RESOURCE_TYPE_LABELS } from '../shared/resource-types';
+import type { SchemaViewerPayload, SchemaViewerSchema } from './shared';
+
+const INLINE_MAX_HEIGHT = '560px';
+
+const FORMAT_LABELS: Record<SchemaViewerSchema['kind'], string> = {
+  json: 'JSON Schema',
+  avro: 'Avro',
+  protobuf: 'Protobuf',
+  code: '',
+};
+
+type SchemaTab = 'code' | 'properties';
+
+function SchemaProperties({ schema, maxHeight }: { schema: SchemaViewerSchema; maxHeight?: string }) {
+  switch (schema.kind) {
+    case 'json':
+      return <JSONSchemaViewer schema={schema.schema} maxHeight={maxHeight} />;
+    case 'avro':
+      return <AvroSchemaViewer schema={schema.schema} maxHeight={maxHeight} showRequired />;
+    case 'protobuf':
+      return <ProtobufSchemaViewer schema={schema.schema} maxHeight={maxHeight} showRequired />;
+    default:
+      return null;
+  }
+}
+
+type SchemaViewerViewProps = {
+  app: App | null;
+  /** The schemas from the latest tool result */
+  payload: SchemaViewerPayload;
+  hostContext?: McpUiHostContext;
+};
+
+export function SchemaViewerView({ app, payload, hostContext }: SchemaViewerViewProps) {
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  // Properties first: it's what people asking to see a schema usually want
+  const [tab, setTab] = useState<SchemaTab>('properties');
+
+  // Show the first schema again when the view gets a new tool result
+  useEffect(() => setSelectedIndex(0), [payload]);
+
+  // The view runs in a sandbox and can't navigate, so EventCatalog opens in the host
+  const openInCatalog = useCallback(
+    (path: string) => app?.openLink({ url: new URL(path, payload.catalogUrl).href }),
+    [app, payload]
+  );
+
+  const { resource, schemas } = payload;
+  const schema = schemas[selectedIndex] ?? schemas[0];
+  // Schemas without a viewer, such as XML Schema, only have their source
+  const hasProperties = schema && schema.kind !== 'code';
+  const activeTab: SchemaTab = hasProperties ? tab : 'code';
+  const isDark = hostContext?.theme === 'dark';
+  const tabs: Array<{ id: SchemaTab; label: string; icon: typeof Code }> = [
+    { id: 'code', label: 'Schema', icon: Code },
+    ...(hasProperties ? [{ id: 'properties' as const, label: 'Properties', icon: Table }] : []),
+  ];
+  const isFullscreen = hostContext?.displayMode === 'fullscreen';
+  const canGoFullscreen = hostContext?.availableDisplayModes?.includes('fullscreen');
+  const buttonClass =
+    '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 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))]">
+            {RESOURCE_TYPE_LABELS[resource.collection] ?? resource.collection}
+          </span>
+          <span className="truncate font-semibold">{resource.name}</span>
+          <span className="shrink-0 text-xs text-[rgb(var(--ec-page-text-muted))]">v{resource.version}</span>
+          {schema && FORMAT_LABELS[schema.kind] && (
+            <span className="shrink-0 text-xs text-[rgb(var(--ec-page-text-muted))]">· {FORMAT_LABELS[schema.kind]}</span>
+          )}
+        </div>
+        <div className="flex shrink-0 gap-1.5">
+          <button type="button" className={buttonClass} onClick={() => openInCatalog(payload.docsPath)}>
+            <ExternalLink aria-hidden className="h-3.5 w-3.5" />
+            Open in EventCatalog
+          </button>
+          {canGoFullscreen && (
+            <button
+              type="button"
+              className={buttonClass}
+              aria-label={isFullscreen ? 'Exit full screen' : 'Full screen'}
+              onClick={() => app?.requestDisplayMode({ mode: isFullscreen ? 'inline' : 'fullscreen' })}
+            >
+              {isFullscreen ? (
+                <Minimize2 aria-hidden className="h-3.5 w-3.5" />
+              ) : (
+                <Maximize2 aria-hidden className="h-3.5 w-3.5" />
+              )}
+            </button>
+          )}
+        </div>
+      </div>
+      {schema && (
+        <div className="flex items-center justify-between gap-3 border-b border-[rgb(var(--ec-page-border))] px-3">
+          <div className="flex items-center gap-1" role="tablist">
+            {tabs.map(({ id, label, icon: Icon }) => (
+              <button
+                key={id}
+                type="button"
+                role="tab"
+                aria-selected={activeTab === id}
+                onClick={() => setTab(id)}
+                className={`-mb-px inline-flex items-center gap-1.5 border-b-2 px-3 py-2 text-xs font-medium transition-colors ${
+                  activeTab === id
+                    ? 'border-[rgb(var(--ec-accent))] text-[rgb(var(--ec-page-text))]'
+                    : 'border-transparent text-[rgb(var(--ec-page-text-muted))] hover:border-[rgb(var(--ec-page-border))] hover:text-[rgb(var(--ec-page-text))]'
+                }`}
+              >
+                <Icon aria-hidden className="h-3.5 w-3.5" />
+                {label}
+              </button>
+            ))}
+          </div>
+          {schemas.length > 1 && (
+            <div className="flex min-w-0 gap-1 overflow-x-auto py-1.5" aria-label="Schemas">
+              {schemas.map((item, index) => (
+                <button
+                  key={`${item.name}-${index}`}
+                  type="button"
+                  aria-pressed={index === selectedIndex}
+                  onClick={() => setSelectedIndex(index)}
+                  className={`whitespace-nowrap rounded-md border px-2 py-1 text-[11px] font-medium transition-colors ${
+                    index === selectedIndex
+                      ? 'border-[rgb(var(--ec-accent)/0.4)] bg-[rgb(var(--ec-accent-subtle))] text-[rgb(var(--ec-page-text))]'
+                      : 'border-[rgb(var(--ec-page-border))] text-[rgb(var(--ec-page-text-muted))] hover:text-[rgb(var(--ec-page-text))]'
+                  }`}
+                >
+                  {item.name}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+      <div className={`p-3 ${isFullscreen ? 'min-h-0 flex-1' : ''}`}>
+        {!schema ? (
+          <p className="text-sm text-[rgb(var(--ec-page-text-muted))]">{resource.name} has no schema.</p>
+        ) : activeTab === 'properties' ? (
+          <SchemaProperties key={selectedIndex} schema={schema} maxHeight={isFullscreen ? undefined : INLINE_MAX_HEIGHT} />
+        ) : (
+          <SchemaCode
+            key={selectedIndex}
+            code={schema.code}
+            language={schema.language}
+            isDark={isDark}
+            maxHeight={isFullscreen ? undefined : INLINE_MAX_HEIGHT}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,98 @@
+/**
+ * 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 { config as configureZod } from 'zod';
+import { createRoot } from 'react-dom/client';
+import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+import { useApp } from '@modelcontextprotocol/ext-apps/react';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+
+// MCP hosts block eval in views, so stop zod (used by the MCP Apps SDK) from probing for it
+configureZod({ jitless: true });
+
+/** The payload for the view: in the result's `_meta` from the model-facing tool, or `structuredContent` from the app-only tool */
+export const getToolResultPayload = <Payload,>(result: CallToolResult, metaKey: string) =>
+  (result._meta?.[metaKey] as Payload | undefined) ?? (result.structuredContent as Payload | undefined);
+
+const applyTheme = (context?: McpUiHostContext) => {
+  if (context?.theme) document.documentElement.setAttribute('data-theme', context.theme);
+};
+
+type McpAppViewOptions<Payload> = {
+  name: string;
+  /** Key of the payload in the model-facing tool result's `_meta` */
+  metaKey: string;
+  /** App-only tool that loads the payload when the host doesn't pass the result's `_meta` to the view */
+  viewTool: string;
+  /** Whether a tool result carried a complete payload */
+  isPayload: (payload: Payload | undefined) => payload is Payload;
+  /** The view tool's arguments, from the model-facing tool result's text */
+  getViewToolArguments: (text: Record<string, any>) => Record<string, unknown>;
+  loadErrorMessage: string;
+};
+
+/** The payload from a tool result, or loaded through the app-only tool when the host doesn't pass `_meta` */
+async function loadPayload<Payload>(app: App, result: CallToolResult, options: McpAppViewOptions<Payload>) {
+  const payload = getToolResultPayload<Payload>(result, options.metaKey);
+  if (options.isPayload(payload)) return payload;
+
+  const text = result.content?.find((item) => item.type === 'text')?.text;
+  const viewResult = await app.callServerTool({
+    name: options.viewTool,
+    arguments: options.getViewToolArguments(JSON.parse(text ?? '{}')),
+  });
+  const loaded = getToolResultPayload<Payload>(viewResult, options.metaKey);
+  if (!options.isPayload(loaded)) throw new Error(options.loadErrorMessage);
+  return loaded;
+}
+
+/**
+ * Connects the view to the MCP host and loads the payload of each tool result shown in it.
+ * Also applies the host's theme (light or dark) and keeps its context (such as the display mode) up to date.
+ */
+export function useMcpAppView<Payload>(options: McpAppViewOptions<Payload>) {
+  const [payload, setPayload] = useState<Payload | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [hostContext, setHostContext] = useState<McpUiHostContext | undefined>();
+
+  const { app, error: connectionError } = useApp({
+    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'] },
+    onAppCreated: (createdApp) => {
+      createdApp.ontoolresult = (result) => {
+        if (result.isError) {
+          setError(result.content?.find((item) => item.type === 'text')?.text ?? options.loadErrorMessage);
+          return;
+        }
+        loadPayload(createdApp, result, options)
+          .then(setPayload)
+          .catch((loadError) => setError(String(loadError?.message ?? loadError)));
+      };
+      createdApp.onhostcontextchanged = (context) => {
+        applyTheme(context);
+        setHostContext((previous) => ({ ...previous, ...context }));
+      };
+    },
+  });
+
+  useEffect(() => {
+    const context = app?.getHostContext();
+    applyTheme(context);
+    setHostContext(context);
+  }, [app]);
+
+  return { app, payload, error: connectionError?.message ?? error, hostContext };
+}
+
+/** Adds the view's styles and renders it */
+export function mountView(View: ComponentType, styles: string) {
+  const style = document.createElement('style');
+  style.textContent = styles;
+  document.head.appendChild(style);
+
+  // No StrictMode: it mounts the view twice, which connects to the host twice
+  createRoot(document.getElementById('root')!).render(<View />);
+}

package/eventcatalog/src/features/mcp/apps/shared/resource-types.ts

@@ -0,0 +1,15 @@
+/** Labels for the collections the MCP App views show, e.g. in a view's header */
+export const RESOURCE_TYPE_LABELS: Record<string, string> = {
+  domains: 'Domain',
+  systems: 'System',
+  services: 'Service',
+  agents: 'Agent',
+  events: 'Event',
+  commands: 'Command',
+  queries: 'Query',
+  flows: 'Flow',
+  channels: 'Channel',
+  entities: 'Entity',
+  containers: 'Data store',
+  'data-products': 'Data product',
+};

package/eventcatalog/src/features/mcp/apps/viewer/shared.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared by the MCP server and the EventCatalog viewer MCP App (view.tsx): one view that shows a
+ * resource's architecture diagram or its schema, so hosts keep one panel open and update it.
+ * Kept free of server-only imports so it can be bundled into the view.
+ */
+import type { ArchitectureDiagramPayload } from '../architecture-diagram/shared';
+import type { SchemaViewerPayload } from '../schema-viewer/shared';
+
+/** The ui:// resource holding the view's HTML (built by scripts/build-mcp-apps.mjs) */
+export const VIEWER_RESOURCE_URI = 'ui://eventcatalog/viewer.html';
+
+/** Key in a tool result's `_meta` carrying what the view shows (not shown to the model) */
+export const VIEWER_META_KEY = 'eventcatalog/view';
+
+/** App-only tool the view calls to load a view when the host doesn't pass the result's `_meta`, or to open another one */
+export const VIEWER_VIEW_TOOL = 'getResourceView';
+
+/** What the viewer can show of a resource */
+export const RESOURCE_VIEWS = ['architecture', 'schema'] as const;
+export type ResourceView = (typeof RESOURCE_VIEWS)[number];
+
+export type ViewerPayload =
+  | { view: 'architecture'; diagram: ArchitectureDiagramPayload }
+  | { view: 'schema'; schema: SchemaViewerPayload };

package/eventcatalog/src/features/mcp/apps/viewer/styles.css

@@ -0,0 +1,25 @@
+/*
+ * The viewer's Tailwind stylesheet (with Tailwind's base reset) and EventCatalog's theme variables.
+ * Only the classes the views and the components they render use, not every template in EventCatalog:
+ * add every component a view imports here, or its Tailwind classes won't be in the viewer's styles.
+ */
+@import 'tailwindcss' source(none);
+@import '../../../../styles/theme.css';
+
+@source './*.tsx';
+@source '../schema-viewer/*.tsx';
+@source '../../../../components/SchemaExplorer/JSONSchemaViewer.tsx';
+@source '../../../../components/SchemaExplorer/AvroSchemaViewer.tsx';
+@source '../../../../components/SchemaExplorer/ProtobufSchemaViewer.tsx';
+
+body {
+  margin: 0;
+  background: rgb(var(--ec-page-bg));
+  color: rgb(var(--ec-page-text));
+  font-family:
+    ui-sans-serif,
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    sans-serif;
+}

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

@@ -0,0 +1,59 @@
+/**
+ * The EventCatalog viewer MCP App: one view that shows what showResource asks for, a resource's
+ * architecture diagram or its schema. Hosts keep one viewer open (ChatGPT, with the result's widget
+ * session) and each new result switches it to the new view. Hosts without MCP Apps support show the
+ * tool's text instead.
+ *
+ * Built into a single HTML file by scripts/build-mcp-apps.mjs and served as a ui:// resource.
+ */
+import { useEffect } from 'react';
+// Tailwind (with its base reset), built from the classes the views use, and EventCatalog's theme variables
+import styles from './styles.css?inline';
+import { mountView, useMcpAppView } from '../shared/app-view';
+import { ArchitectureDiagramView, architectureDiagramStyles, VISUALISER_BODY_CLASS } from '../architecture-diagram/view';
+import { SchemaViewerView } from '../schema-viewer/view';
+import { VIEWER_META_KEY, VIEWER_VIEW_TOOL, type ViewerPayload } from './shared';
+
+const isViewerPayload = (payload?: ViewerPayload): payload is ViewerPayload =>
+  (payload?.view === 'architecture' && Boolean(payload.diagram?.view)) ||
+  (payload?.view === 'schema' && Boolean(payload.schema?.schemas));
+
+const VIEW_OPTIONS = {
+  name: 'EventCatalog',
+  metaKey: VIEWER_META_KEY,
+  viewTool: VIEWER_VIEW_TOOL,
+  isPayload: isViewerPayload,
+  getViewToolArguments: ({ view, resourceId, resourceVersion, resourceCollection }: Record<string, any>) => ({
+    view,
+    resourceId,
+    resourceVersion,
+    resourceCollection,
+  }),
+  loadErrorMessage: 'This could not be loaded from EventCatalog',
+};
+
+function Viewer() {
+  const { app, payload, error, hostContext } = useMcpAppView(VIEW_OPTIONS);
+
+  // The visualiser's theme variables would override EventCatalog's, so they only apply to the diagram
+  const isDiagram = payload?.view === 'architecture';
+  useEffect(() => {
+    document.body.classList.toggle(VISUALISER_BODY_CLASS, isDiagram);
+  }, [isDiagram]);
+
+  if (error) {
+    return <p className="p-4 text-sm">{error}</p>;
+  }
+
+  if (!payload) {
+    return <p className="p-4 text-sm text-[rgb(var(--ec-page-text-muted))]">Loading from EventCatalog…</p>;
+  }
+
+  return payload.view === 'architecture' ? (
+    <ArchitectureDiagramView app={app} payload={payload.diagram} hostContext={hostContext} />
+  ) : (
+    <SchemaViewerView app={app} payload={payload.schema} hostContext={hostContext} />
+  );
+}
+
+mountView(Viewer, [styles, architectureDiagramStyles].join('\n'));

package/eventcatalog/src/features/mcp/mcp-app-icons.ts

@@ -0,0 +1,63 @@
+/**
+ * Embeds the icons shown on diagram nodes (e.g. a service's language, a database's engine) as data
+ * URIs, for MCP App views. Views run in a sandbox in the MCP host, where icon paths served by
+ * EventCatalog (e.g. /icons/languages/nodejs.svg) don't load.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const MIME_TYPES: Record<string, string> = {
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.gif': 'image/gif',
+};
+
+const MAX_DEPTH = 6;
+
+async function toDataUri(iconPath: string, publicDirectory: string) {
+  // Icons from other sites are left as they are
+  if (!iconPath.startsWith('/')) return undefined;
+
+  const filePath = path.resolve(publicDirectory, `.${iconPath.split(/[?#]/)[0]}`);
+  if (!filePath.startsWith(path.resolve(publicDirectory) + path.sep)) return undefined;
+
+  const mimeType = MIME_TYPES[path.extname(filePath).toLowerCase()];
+  if (!mimeType) return undefined;
+
+  try {
+    return `data:${mimeType};base64,${(await fs.readFile(filePath)).toString('base64')}`;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every `styles.icon` in the node's data, which is where nodes keep their icon */
+function collectIconStyles(value: unknown, found: Array<{ icon: string }>, depth = 0) {
+  if (!value || typeof value !== 'object' || depth > MAX_DEPTH) return;
+  for (const [key, child] of Object.entries(value)) {
+    if (key === 'styles' && child && typeof (child as any).icon === 'string') found.push(child as { icon: string });
+    else collectIconStyles(child, found, depth + 1);
+  }
+}
+
+/** A copy of the nodes with their icons embedded (the nodes given are not changed) */
+export async function inlineNodeIcons<T extends { data?: unknown }>(nodes: T[], publicDirectory: string): Promise<T[]> {
+  const copy = structuredClone(nodes);
+  const styles: Array<{ icon: string }> = [];
+  copy.forEach((node) => collectIconStyles(node.data, styles));
+
+  const dataUris = new Map<string, string | undefined>();
+  await Promise.all(
+    [...new Set(styles.map((style) => style.icon))].map(async (icon) =>
+      dataUris.set(icon, await toDataUri(icon, publicDirectory))
+    )
+  );
+
+  styles.forEach((style) => {
+    style.icon = dataUris.get(style.icon) ?? style.icon;
+  });
+  return copy;
+}