@eventcatalog/core 4.0.6 → 4.0.7

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 = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/analytics.js

@@ -1,7 +1,7 @@
 import {
   raiseEvent
-} from "../chunk-FHVBLKWN.js";
-import "../chunk-Z7BGWB5J.js";
+} from "../chunk-WDA5QYVD.js";
+import "../chunk-RBBWHWE4.js";
 export {
   raiseEvent
 };

package/dist/analytics/log-build.cjs

@@ -140,7 +140,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_os = __toESM(require("os"), 1);
 
 // package.json
-var version = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/analytics/log-build.js

@@ -1,9 +1,9 @@
 import {
   log_build_default
-} from "../chunk-ZYWUN3T3.js";
-import "../chunk-FHVBLKWN.js";
+} from "../chunk-ARHL5SPG.js";
+import "../chunk-WDA5QYVD.js";
 import "../chunk-DAOXTQVS.js";
-import "../chunk-Z7BGWB5J.js";
+import "../chunk-RBBWHWE4.js";
 import "../chunk-6QENHZZP.js";
 export {
   log_build_default as default

package/dist/{chunk-ZYWUN3T3.js → chunk-ARHL5SPG.js}

@@ -1,6 +1,6 @@
 import {
   raiseEvent
-} from "./chunk-FHVBLKWN.js";
+} from "./chunk-WDA5QYVD.js";
 import {
   countResources,
   serializeCounts

package/dist/{chunk-ZXAF4JO7.js → chunk-IMCMPLIJ.js}

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

package/dist/{chunk-Z7BGWB5J.js → chunk-RBBWHWE4.js}

@@ -1,5 +1,5 @@
 // package.json
-var version = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/{chunk-FHVBLKWN.js → chunk-WDA5QYVD.js}

@@ -1,6 +1,6 @@
 import {
   VERSION
-} from "./chunk-Z7BGWB5J.js";
+} from "./chunk-RBBWHWE4.js";
 
 // src/analytics/analytics.js
 import os from "os";

package/dist/{chunk-7443A7LZ.js → chunk-ZOFYLCPF.js}

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

package/dist/constants.cjs

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

package/dist/constants.js

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

package/dist/eventcatalog.cjs

@@ -144,7 +144,7 @@ var verifyRequiredFieldsAreInCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/eventcatalog.js

@@ -1,16 +1,16 @@
 import {
   log_build_default
-} from "./chunk-ZYWUN3T3.js";
+} from "./chunk-ARHL5SPG.js";
 import {
   runMigrations
 } from "./chunk-XUAF2H54.js";
 import "./chunk-CA4U2JP7.js";
 import {
   generate
-} from "./chunk-7443A7LZ.js";
+} from "./chunk-ZOFYLCPF.js";
 import {
   logger
-} from "./chunk-ZXAF4JO7.js";
+} from "./chunk-IMCMPLIJ.js";
 import {
   resolve_catalog_dependencies_default
 } from "./chunk-LHR4G2UO.js";
@@ -20,7 +20,7 @@ import {
 import {
   watch
 } from "./chunk-O3Y2G6CY.js";
-import "./chunk-FHVBLKWN.js";
+import "./chunk-WDA5QYVD.js";
 import "./chunk-DAOXTQVS.js";
 import {
   catalogToAstro
@@ -28,7 +28,7 @@ import {
 import "./chunk-VC6VUJIX.js";
 import {
   VERSION
-} from "./chunk-Z7BGWB5J.js";
+} from "./chunk-RBBWHWE4.js";
 import {
   linkCoreNodeModules,
   resolveInstalledCoreNodeModules

package/dist/generate.cjs

@@ -108,7 +108,7 @@ var getEventCatalogConfigFile = async (projectDirectory) => {
 var import_picocolors = __toESM(require("picocolors"), 1);
 
 // package.json
-var version = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/generate.js

@@ -1,8 +1,8 @@
 import {
   generate
-} from "./chunk-7443A7LZ.js";
-import "./chunk-ZXAF4JO7.js";
-import "./chunk-Z7BGWB5J.js";
+} from "./chunk-ZOFYLCPF.js";
+import "./chunk-IMCMPLIJ.js";
+import "./chunk-RBBWHWE4.js";
 import "./chunk-6QENHZZP.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 = "4.0.6";
+var version = "4.0.7";
 
 // src/constants.ts
 var VERSION = version;

package/dist/utils/cli-logger.js

@@ -1,7 +1,7 @@
 import {
   logger
-} from "../chunk-ZXAF4JO7.js";
-import "../chunk-Z7BGWB5J.js";
+} from "../chunk-IMCMPLIJ.js";
+import "../chunk-RBBWHWE4.js";
 export {
   logger
 };

package/eventcatalog/src/components/ChatPanel/ChatPanel.tsx

@@ -1,12 +1,14 @@
 import { useEffect, useRef, useCallback, useState, useMemo, memo } from 'react';
 import { X, Square, Trash2, BookOpen, Copy, Check, Maximize2, Minimize2, Wrench, ChevronDown, MessageSquare } from 'lucide-react';
 import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
 import ReactMarkdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { oneDark } from 'react-syntax-highlighter/dist/cjs/styles/prism';
 import * as Dialog from '@radix-ui/react-dialog';
 import * as Popover from '@radix-ui/react-popover';
+import { buildUrl } from '@utils/url-builder';
 
 interface ToolMetadata {
   name: string;
@@ -527,6 +529,8 @@ const ChatPanel = ({ isOpen, onClose }: ChatPanelProps) => {
   const [isFullscreen, setIsFullscreen] = useState(false);
   const [tools, setTools] = useState<ToolMetadata[]>([]);
   const [showScrollButton, setShowScrollButton] = useState(false);
+  const chatApiUrl = useMemo(() => buildUrl('/api/chat', true), []);
+  const chatTransport = useMemo(() => new DefaultChatTransport({ api: chatApiUrl }), [chatApiUrl]);
 
   // Sort tools with custom ones first
   const sortedTools = useMemo(() => {
@@ -540,7 +544,7 @@ const ChatPanel = ({ isOpen, onClose }: ChatPanelProps) => {
   // Fetch available tools when panel opens
   useEffect(() => {
     if (isOpen && tools.length === 0) {
-      fetch('/api/chat')
+      fetch(chatApiUrl)
         .then((res) => res.json())
         .then((data) => {
           if (data.tools) {
@@ -597,7 +601,7 @@ const ChatPanel = ({ isOpen, onClose }: ChatPanelProps) => {
     setShowScrollButton(!isNearBottom);
   }, []);
 
-  const { messages, sendMessage, stop, status, setMessages, error } = useChat();
+  const { messages, sendMessage, stop, status, setMessages, error } = useChat({ transport: chatTransport });
 
   // Extract user-friendly error message
   const errorMessage = error?.message || 'Something went wrong. Please try again.';

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/utils/json-schema-refs.ts

@@ -0,0 +1,158 @@
+type Fetcher = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+type ResolveSchemaRefsOptions = {
+  baseUrl: string;
+  headers?: HeadersInit;
+  fetcher?: Fetcher;
+  maxDepth?: number;
+};
+
+type ResolveContext = Required<Pick<ResolveSchemaRefsOptions, 'baseUrl' | 'fetcher' | 'maxDepth'>> & {
+  headers?: HeadersInit;
+  cache: Map<string, unknown>;
+};
+
+type RefTarget = {
+  schema: unknown;
+  root: unknown;
+  baseUrl: string;
+  refKey: string;
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const decodeJsonPointerSegment = (segment: string) => decodeURIComponent(segment).replace(/~1/g, '/').replace(/~0/g, '~');
+
+const resolveJsonPointer = (document: unknown, pointer: string): unknown => {
+  if (!pointer || pointer === '#') return document;
+
+  const path = pointer.startsWith('#') ? pointer.slice(1) : pointer;
+  if (!path) return document;
+  if (!path.startsWith('/')) return undefined;
+
+  return path
+    .slice(1)
+    .split('/')
+    .map(decodeJsonPointerSegment)
+    .reduce<unknown>((current, segment) => {
+      if (current === undefined || current === null) return undefined;
+      if (Array.isArray(current)) return current[Number(segment)];
+      if (isObject(current)) return current[segment];
+      return undefined;
+    }, document);
+};
+
+const splitRef = (ref: string, baseUrl: string) => {
+  const [urlPart = '', fragmentPart = ''] = ref.split('#');
+  const url = urlPart ? new URL(urlPart, baseUrl).toString() : baseUrl;
+  return {
+    url,
+    fragment: `#${fragmentPart}`,
+    refKey: `${url}#${fragmentPart}`,
+  };
+};
+
+const loadRemoteDocument = async (url: string, context: ResolveContext) => {
+  if (context.cache.has(url)) return context.cache.get(url);
+
+  const response = await context.fetcher(url, {
+    headers: context.headers,
+  });
+
+  if (!response.ok) {
+    throw new Error(`Failed to fetch referenced schema: ${response.status} ${response.statusText}`);
+  }
+
+  const document = await response.json();
+  context.cache.set(url, document);
+  return document;
+};
+
+const resolveRef = async (
+  ref: string,
+  root: unknown,
+  currentBaseUrl: string,
+  context: ResolveContext
+): Promise<RefTarget | undefined> => {
+  const { url, fragment, refKey } = splitRef(ref, currentBaseUrl);
+  const isCurrentDocument = url === currentBaseUrl;
+  const document = isCurrentDocument ? root : await loadRemoteDocument(url, context);
+  const schema = resolveJsonPointer(document, fragment);
+
+  if (schema === undefined) return undefined;
+
+  return {
+    schema,
+    root: document,
+    baseUrl: url,
+    refKey,
+  };
+};
+
+const resolveNode = async (
+  node: unknown,
+  root: unknown,
+  currentBaseUrl: string,
+  context: ResolveContext,
+  seenRefs: Set<string>,
+  depth: number
+): Promise<unknown> => {
+  if (depth > context.maxDepth) return node;
+
+  if (Array.isArray(node)) {
+    return Promise.all(node.map((item) => resolveNode(item, root, currentBaseUrl, context, seenRefs, depth)));
+  }
+
+  if (!isObject(node)) return node;
+
+  const ref = typeof node.$ref === 'string' ? node.$ref : undefined;
+  if (ref) {
+    const target = await resolveRef(ref, root, currentBaseUrl, context);
+    if (!target || seenRefs.has(target.refKey)) return { ...node };
+
+    const nextSeenRefs = new Set(seenRefs);
+    nextSeenRefs.add(target.refKey);
+
+    const resolvedSchema = await resolveNode(target.schema, target.root, target.baseUrl, context, nextSeenRefs, depth + 1);
+    const siblingEntries = Object.entries(node).filter(([key]) => key !== '$ref');
+    const resolvedSiblings = Object.fromEntries(
+      await Promise.all(
+        siblingEntries.map(async ([key, value]) => [
+          key,
+          await resolveNode(value, root, currentBaseUrl, context, seenRefs, depth),
+        ])
+      )
+    );
+
+    if (isObject(resolvedSchema)) {
+      return {
+        ...resolvedSchema,
+        ...resolvedSiblings,
+      };
+    }
+
+    return Object.keys(resolvedSiblings).length > 0 ? resolvedSiblings : resolvedSchema;
+  }
+
+  return Object.fromEntries(
+    await Promise.all(
+      Object.entries(node).map(async ([key, value]) => [
+        key,
+        await resolveNode(value, root, currentBaseUrl, context, seenRefs, depth),
+      ])
+    )
+  );
+};
+
+export const resolveSchemaRefs = async (schema: unknown, options: ResolveSchemaRefsOptions): Promise<unknown> => {
+  const context: ResolveContext = {
+    baseUrl: options.baseUrl,
+    headers: options.headers,
+    fetcher: options.fetcher ?? fetch,
+    maxDepth: options.maxDepth ?? 25,
+    cache: new Map([[options.baseUrl, schema]]),
+  };
+
+  return resolveNode(schema, schema, options.baseUrl, context, new Set(), 0);
+};

package/package.json

@@ -7,7 +7,7 @@
   },
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
-  "version": "4.0.6",
+  "version": "4.0.7",
   "publishConfig": {
     "access": "public"
   },
@@ -116,9 +116,9 @@
     "update-notifier": "^7.3.1",
     "uuid": "^10.0.0",
     "zod": "^4.3.6",
+    "@eventcatalog/linter": "1.1.4",
     "@eventcatalog/sdk": "2.25.0",
-    "@eventcatalog/visualiser": "^4.0.0",
-    "@eventcatalog/linter": "1.1.3"
+    "@eventcatalog/visualiser": "^4.0.1"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",