From 429f04240d8a0e9b86699df32d1b32ae578f9af5 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Mon, 16 Feb 2026 17:24:32 +0100
Subject: [PATCH 01/23] feat: enhance "Import from URL" with remote $refs and
 URL tracking

Merge Load/Import URL functionality into single "Import from URL" button
that updates browser URL, supports remote $refs, and preserves source
URL in localStorage for persistent remote references after editing.
---
 .../src/components/Editor/MonacoWrapper.tsx   |  9 +-
 apps/studio/src/components/Modals/index.tsx   |  1 +
 apps/studio/src/components/StudioWrapper.tsx  | 36 ++++---
 apps/studio/src/services/editor.service.tsx   | 95 +++++++++++++++----
 apps/studio/src/services/monaco.service.ts    | 13 ++-
 apps/studio/src/state/files.state.ts          | 29 +++++-
 6 files changed, 142 insertions(+), 41 deletions(-)

diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index 0c47b4a18..326fde537 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -17,11 +17,14 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
 
   const onChange = useMemo(() => {
     return debounce((v: string) => {
-      editorSvc.updateState({ content: v, file: { from: 'storage', source: undefined } });
+      // Preserve the current source URL instead of setting to undefined
+      const currentSource = file?.source;
+      editorSvc.updateState({ content: v, file: { from: 'storage', source: currentSource } });
       autoSaving && editorSvc.saveToLocalStorage(v, false);
-      parserSvc.parse('asyncapi', v);
+      // Pass source to parser to maintain remote $refs support
+      parserSvc.parse('asyncapi', v, { source: currentSource });
     }, savingDelay);
-  }, [autoSaving, savingDelay]);
+  }, [autoSaving, savingDelay, file?.source]);
 
   return (
     <MonacoEditor
diff --git a/apps/studio/src/components/Modals/index.tsx b/apps/studio/src/components/Modals/index.tsx
index 06cedfbcb..048d4991b 100644
--- a/apps/studio/src/components/Modals/index.tsx
+++ b/apps/studio/src/components/Modals/index.tsx
@@ -7,6 +7,7 @@ export * from './ConvertToLatestModal';
 export * from './ImportBase64Modal';
 export * from './ImportURLModal';
 export * from './ImportUUIDModal';
+
 export * from './NewFileModal';
 export * from './RedirectedModal';
 export * from './ConfirmNewFileModal';
\ No newline at end of file
diff --git a/apps/studio/src/components/StudioWrapper.tsx b/apps/studio/src/components/StudioWrapper.tsx
index 62c3d294f..fbafbf474 100644
--- a/apps/studio/src/components/StudioWrapper.tsx
+++ b/apps/studio/src/components/StudioWrapper.tsx
@@ -10,20 +10,29 @@ import { driverObj } from '@/helpers/driver';
 
 function configureMonacoEnvironment() {
   if (typeof window !== 'undefined') {
+    const editorWorkerUrl = 'monaco-editor/esm/vs/editor/editor.worker';
+
     window.MonacoEnvironment = {
       getWorker(_, label) {
-        switch (label) {
-        case 'editorWorkerService':
-          return new Worker(new URL('monaco-editor/esm/vs/editor/editor.worker', import.meta.url));
-        case 'json':
-          return new Worker(
-            new URL('monaco-editor/esm/vs/language/json/json.worker', import.meta.url),
-          );
-        case 'yaml':
-        case 'yml':
-          return new Worker(new URL('monaco-yaml/yaml.worker', import.meta.url));
-        default:
-          throw new Error(`Unknown worker ${label}`);
+        try {
+          switch (label) {
+          case 'editorWorkerService':
+            return new Worker(new URL(editorWorkerUrl, import.meta.url));
+          case 'json':
+            return new Worker(
+              new URL('monaco-editor/esm/vs/language/json/json.worker', import.meta.url),
+            );
+          case 'yaml':
+          case 'yml':
+            return new Worker(new URL('monaco-yaml/yaml.worker', import.meta.url));
+          default:
+            console.warn(`Unknown worker label: ${label}, falling back to editor worker`);
+            return new Worker(new URL(editorWorkerUrl, import.meta.url));
+          }
+        } catch (error) {
+          console.error(`Failed to create worker for ${label}:`, error);
+          // Fallback to editor worker
+          return new Worker(new URL(editorWorkerUrl, import.meta.url));
         }
       },
     };
@@ -34,9 +43,10 @@ export default function StudioWrapper() {
   const [services, setServices] = useState<Services>();
   useEffect(() => {
     const fetchData = async () => {
+      // Configure Monaco environment BEFORE creating services
+      configureMonacoEnvironment();
       const servicess = await createServices();
       setServices(servicess);
-      configureMonacoEnvironment();
       const alreadyVisitedSession = sessionStorage.getItem('alreadyVisited');
       const alreadyVisitedLocal = localStorage.getItem('alreadyVisited');
       if (!alreadyVisitedSession && !alreadyVisitedLocal) {
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 21b0c9309..8cdde7fd4 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -103,24 +103,36 @@ export class EditorService extends AbstractService {
   }
 
   async importFromURL(url: string): Promise<void> {
-    if (url) {
-      return fetch(url)
-        .then(res => res.text())
-        .then(async text => {
-          this.updateState({ 
-            content: text, 
-            updateModel: true, 
-            file: { 
-              source: url, 
-              from: 'url' 
-            },
-          });
-        })
-        .catch(err => {
-          console.error(err);
-          throw err;
-        });
+    if (!url) {
+      throw new Error('URL is required');
     }
+
+    // Update browser URL with ?url= parameter (no page reload)
+    const currentUrl = window.location.href.split('?')[0];
+    window.history.pushState({}, '', `${currentUrl}?url=${url}`);
+
+    return fetch(url)
+      .then(res => res.text())
+      .then(async text => {
+        const language = this.svcs.formatSvc.retrieveLangauge(text);
+
+        this.updateState({
+          content: text,
+          updateModel: true,
+          file: {
+            source: url,
+            from: 'url',
+            language,
+          },
+        });
+
+        // Parse with source for remote $refs resolution
+        await this.svcs.parserSvc.parse('asyncapi', text, { source: url });
+      })
+      .catch(err => {
+        console.error(err);
+        throw err;
+      });
   }
 
   async importFile(files: FileList | null) {
@@ -277,12 +289,22 @@ export class EditorService extends AbstractService {
 
   saveToLocalStorage(editorValue?: string, notify = true) {
     editorValue = editorValue || this.value;
-    localStorage.setItem('document', editorValue);
+
+    // Get current source URL to preserve it
+    const currentFile = filesState.getState().files['asyncapi'];
+    const source = currentFile?.source;
+
+    // Store both content and source in localStorage
+    const documentData = {
+      content: editorValue,
+      source: source || undefined,
+    };
+    localStorage.setItem('document', JSON.stringify(documentData));
 
     const { updateFile } = filesState.getState();
     updateFile('asyncapi', {
       from: 'storage',
-      source: undefined,
+      source, // Preserve the source URL
       modified: false,
     });
 
@@ -308,7 +330,40 @@ export class EditorService extends AbstractService {
   }
 
   getFromLocalStorage() {
-    return localStorage.getItem('document');
+    const stored = localStorage.getItem('document');
+    if (!stored) return null;
+
+    try {
+      // Try to parse as JSON (new format)
+      const parsed = JSON.parse(stored);
+      if (parsed && typeof parsed === 'object' && 'content' in parsed) {
+        return parsed.content; // Return just the content for compatibility
+      }
+    } catch {
+      // If parsing fails, it's the old format (plain string)
+      return stored;
+    }
+
+    // Fallback to treating as plain string
+    return stored;
+  }
+
+  getSourceFromLocalStorage() {
+    const stored = localStorage.getItem('document');
+    if (!stored) return undefined;
+
+    try {
+      // Try to parse as JSON (new format)
+      const parsed = JSON.parse(stored);
+      if (parsed && typeof parsed === 'object' && 'source' in parsed) {
+        return parsed.source;
+      }
+    } catch {
+      // If parsing fails, it's the old format (no source)
+      return undefined;
+    }
+
+    return undefined;
   }
 
   private applyMarkersAndDecorations(diagnostics: Diagnostic[] = []) {
diff --git a/apps/studio/src/services/monaco.service.ts b/apps/studio/src/services/monaco.service.ts
index aad59eaeb..d9edb5022 100644
--- a/apps/studio/src/services/monaco.service.ts
+++ b/apps/studio/src/services/monaco.service.ts
@@ -85,9 +85,16 @@ export class MonacoService extends AbstractService {
     if (process.env.NODE_ENV === 'test') {
       return;
     }
-    
-    const monaco = this.monacoInstance = await import('monaco-editor');
-    loader.config({ monaco });
+
+    try {
+      // Use the loader to get Monaco instead of direct import
+      this.monacoInstance = await loader.init();
+    } catch (error) {
+      console.error('Failed to load Monaco:', error);
+      // Fallback to direct import if loader fails
+      const monaco = this.monacoInstance = await import('monaco-editor');
+      loader.config({ monaco });
+    }
   }
 
   private setMonacoTheme() {
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index 2ccd359e3..a3f6cbc63 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -1,6 +1,31 @@
 import { create } from 'zustand';
 
-const document = typeof window !== 'undefined' ? localStorage.getItem('document') : undefined
+// Helper function to extract content and source from localStorage
+const getDocumentFromLocalStorage = () => {
+  if (typeof window === 'undefined') return { content: undefined, source: undefined };
+
+  const stored = localStorage.getItem('document');
+  if (!stored) return { content: undefined, source: undefined };
+
+  try {
+    // Try to parse as JSON (new format)
+    const parsed = JSON.parse(stored);
+    if (parsed && typeof parsed === 'object' && 'content' in parsed) {
+      return {
+        content: parsed.content,
+        source: parsed.source || undefined,
+      };
+    }
+  } catch {
+    // If parsing fails, it's the old format (plain string)
+    return { content: stored, source: undefined };
+  }
+
+  // Fallback to treating as plain string
+  return { content: stored, source: undefined };
+};
+
+const { content: document, source: documentSource } = getDocumentFromLocalStorage();
 const schema =
   document || `asyncapi: 3.0.0
 info:
@@ -240,7 +265,7 @@ export const filesState = create<FilesState & FilesActions>(set => ({
       name: 'asyncapi',
       content: schema,
       from: 'storage',
-      source: undefined,
+      source: documentSource, // Use source from localStorage if available
       language: schema.trimStart()[0] === '{' ? 'json' : 'yaml',
       modified: false,
       stat: {

From dbbaab49d256149c846170f68f7cb7e871259a3c Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Mon, 2 Mar 2026 21:21:06 +0100
Subject: [PATCH 02/23] wicg-file-system-access

---
 apps/studio/package.json  | 1 +
 apps/studio/tsconfig.json | 2 +-
 pnpm-lock.yaml            | 8 ++++++++
 3 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/apps/studio/package.json b/apps/studio/package.json
index fcb79c44c..dfc18d298 100644
--- a/apps/studio/package.json
+++ b/apps/studio/package.json
@@ -120,6 +120,7 @@
     "@types/node": "^18.11.9",
     "@types/react": "^18.0.25",
     "@types/react-dom": "^18.0.9",
+    "@types/wicg-file-system-access": "^2023.10.7",
     "assert": "^2.0.0",
     "autoprefixer": "^10.4.13",
     "browserify-zlib": "^0.2.0",
diff --git a/apps/studio/tsconfig.json b/apps/studio/tsconfig.json
index 47e8861dc..45fa5c5e4 100644
--- a/apps/studio/tsconfig.json
+++ b/apps/studio/tsconfig.json
@@ -29,7 +29,7 @@
         "./public/*"
       ]
     },
-    "types": ["cypress"]
+    "types": ["cypress", "wicg-file-system-access"]
   },
   "include": [
     "next-env.d.ts",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5bdf572e1..5d9ca31d1 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -335,6 +335,9 @@ importers:
       '@types/json-schema':
         specifier: ^7.0.15
         version: 7.0.15
+      '@types/wicg-file-system-access':
+        specifier: ^2023.10.7
+        version: 2023.10.7
       assert:
         specifier: ^2.0.0
         version: 2.0.0
@@ -4657,6 +4660,9 @@ packages:
   '@types/uuid@9.0.8':
     resolution: {integrity: sha512-jg+97EGIcY9AGHJJRaaPVgetKDsrTgbRjQ5Msgjh/DQKEFl0DtyRr/VCOyD1T2R1MNeWPK/u7JoGhlDZnKBAfA==}
 
+  '@types/wicg-file-system-access@2023.10.7':
+    resolution: {integrity: sha512-g49ijasEJvCd7ifmAY2D0wdEtt1xRjBbA33PJTiv8mKBr7DoMsPeISoJ8oQOTopSRi+FBWPpPW5ouDj2QPKtGA==}
+
   '@types/ws@8.18.1':
     resolution: {integrity: sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg==}
 
@@ -19171,6 +19177,8 @@ snapshots:
 
   '@types/uuid@9.0.8': {}
 
+  '@types/wicg-file-system-access@2023.10.7': {}
+
   '@types/ws@8.18.1':
     dependencies:
       '@types/node': 20.4.6

From e45d614ac40412cd07f352305582c0e05570027f Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Tue, 3 Mar 2026 11:59:31 +0100
Subject: [PATCH 03/23] grants folder access

---
 .../src/components/Editor/EditorDropdown.tsx  |  30 +++-
 .../src/components/Editor/ImportDropdown.tsx  |  32 +++-
 .../src/components/Editor/MonacoWrapper.tsx   |   7 +-
 .../src/components/Modals/OpenFolderModal.tsx |  47 ++++++
 apps/studio/src/components/Modals/index.tsx   |   1 +
 apps/studio/src/components/StudioWrapper.tsx  |  43 +++---
 apps/studio/src/services/app.service.ts       |   4 +-
 apps/studio/src/services/editor.service.tsx   | 107 +++++++++++--
 .../src/services/local-file-resolver.ts       | 143 ++++++++++++++++++
 apps/studio/src/services/parser.service.ts    |  76 +++++++++-
 apps/studio/src/state/files.state.ts          |  19 ++-
 11 files changed, 449 insertions(+), 60 deletions(-)
 create mode 100644 apps/studio/src/components/Modals/OpenFolderModal.tsx
 create mode 100644 apps/studio/src/services/local-file-resolver.ts

diff --git a/apps/studio/src/components/Editor/EditorDropdown.tsx b/apps/studio/src/components/Editor/EditorDropdown.tsx
index cc3506984..7aa63f0ac 100644
--- a/apps/studio/src/components/Editor/EditorDropdown.tsx
+++ b/apps/studio/src/components/Editor/EditorDropdown.tsx
@@ -9,6 +9,7 @@ import {
   GeneratorModal,
   ConvertModal,
   ImportUUIDModal,
+  OpenFolderModal,
 } from '../Modals';
 import { Dropdown } from '../common';
 
@@ -28,10 +29,10 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
     <button
       type="button"
       className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-      title="Import from URL"
+      title="Open URL"
       onClick={() => show(ImportURLModal)}
     >
-      Import from URL
+      Open URL
     </button>
   );
 
@@ -46,14 +47,17 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
     </button>
   );
 
+  const fileInputRef = React.useRef<HTMLInputElement>(null);
+
   const importFileButton = (
     <label
       className="block px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 cursor-pointer"
-      title="Import File"
+      title="Open File"
     >
       <input
+        ref={fileInputRef}
         type="file"
-        accept='.yaml, .yml, .json'
+        accept='.yaml, .yml, .json, .avsc'
         style={{ position: 'fixed', top: '-100em' }}
         onChange={event => {
           toast.promise(editorSvc.importFile(event.target.files), {
@@ -73,12 +77,25 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
               </div>
             ),
           });
+          // Reset so the same file can be re-imported
+          if (fileInputRef.current) fileInputRef.current.value = '';
         }}
       />
-      Import File
+      Open File
     </label>
   );
 
+  const openFolderButton = (
+    <button
+      type="button"
+      className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
+      title="Open Folder"
+      onClick={() => show(OpenFolderModal)}
+    >
+      Open Folder
+    </button>
+  );
+
   const importBase64Button = (
     <button
       type="button"
@@ -258,6 +275,9 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
           <li className="hover:bg-gray-900">
             {importFileButton}
           </li>
+          <li className="hover:bg-gray-900">
+            {openFolderButton}
+          </li>
           <li className="hover:bg-gray-900">
             {importBase64Button}
           </li>
diff --git a/apps/studio/src/components/Editor/ImportDropdown.tsx b/apps/studio/src/components/Editor/ImportDropdown.tsx
index 61981f6b7..f943756b8 100644
--- a/apps/studio/src/components/Editor/ImportDropdown.tsx
+++ b/apps/studio/src/components/Editor/ImportDropdown.tsx
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import toast from 'react-hot-toast';
 import { show } from '@ebay/nice-modal-react';
 import { FaFileImport } from 'react-icons/fa';
@@ -7,6 +7,7 @@ import {
   ImportURLModal,
   ImportBase64Modal,
   ImportUUIDModal,
+  OpenFolderModal,
 } from '../Modals';
 
 import { Dropdown, Tooltip } from '../common';
@@ -14,14 +15,15 @@ import { useServices } from '@/services';
 
 export const ImportDropdown: React.FC = () => {
   const { editorSvc } = useServices();
+  const fileInputRef = useRef<HTMLInputElement>(null);
 
   return (
     <Dropdown 
       opener={
         <Tooltip content="Import" placement="top" hideOnClick={true}>
-          <button className="bg-inherit">
+          <span>
             <FaFileImport />
-          </button>
+          </span>
         </Tooltip>
       }
       buttonHoverClassName="text-gray-500 hover:text-white"
@@ -32,21 +34,22 @@ export const ImportDropdown: React.FC = () => {
           <button
             type="button"
             className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-            title="Import from URL"
+            title="Open URL"
             onClick={() => show(ImportURLModal)}
           >
-                Import from URL
+                Open URL
           </button>
         </li>
 
         <li className="hover:bg-gray-900">
           <label
             className="block px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 cursor-pointer"
-            title="Import File"
+            title="Open File"
           >
             <input
+              ref={fileInputRef}
               type="file"
-              accept='.yaml, .yml, .json'
+              accept='.yaml, .yml, .json, .avsc'
               style={{ position: 'fixed', top: '-100em' }}
               onChange={event => {
                 toast.promise(editorSvc.importFile(event.target.files), {
@@ -66,12 +69,25 @@ export const ImportDropdown: React.FC = () => {
                     </div>
                   ),
                 });
+                // Reset so the same file can be re-imported
+                if (fileInputRef.current) fileInputRef.current.value = '';
               }}
             />
-            Import File
+            Open File
           </label>
         </li>
 
+        <li className="hover:bg-gray-900">
+          <button
+            type="button"
+            className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
+            title="Open Folder"
+            onClick={() => show(OpenFolderModal)}
+          >
+            Open Folder
+          </button>
+        </li>
+
         <li className="hover:bg-gray-900">
           <button
             type="button"
diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index 326fde537..c235e5f57 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -11,7 +11,7 @@ import type { EditorProps as MonacoEditorProps } from '@monaco-editor/react';
 export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
   ...props
 }) => {
-  const { editorSvc, parserSvc } = useServices();
+  const { editorSvc } = useServices();
   const { autoSaving, savingDelay } = useSettingsState(state => state.editor);
   const file = useFilesState(state => state.files['asyncapi']);
 
@@ -19,10 +19,9 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
     return debounce((v: string) => {
       // Preserve the current source URL instead of setting to undefined
       const currentSource = file?.source;
-      editorSvc.updateState({ content: v, file: { from: 'storage', source: currentSource } });
+      editorSvc.updateState({ content: v, file: { source: currentSource } });
       autoSaving && editorSvc.saveToLocalStorage(v, false);
-      // Pass source to parser to maintain remote $refs support
-      parserSvc.parse('asyncapi', v, { source: currentSource });
+      // subscribeToFiles will trigger a re-parse when content changes
     }, savingDelay);
   }, [autoSaving, savingDelay, file?.source]);
 
diff --git a/apps/studio/src/components/Modals/OpenFolderModal.tsx b/apps/studio/src/components/Modals/OpenFolderModal.tsx
new file mode 100644
index 000000000..9079d8369
--- /dev/null
+++ b/apps/studio/src/components/Modals/OpenFolderModal.tsx
@@ -0,0 +1,47 @@
+import toast from 'react-hot-toast';
+import { create } from '@ebay/nice-modal-react';
+
+import { ConfirmModal } from './ConfirmModal';
+
+import { useServices } from '../../services';
+
+export const OpenFolderModal = create(() => {
+  const { editorSvc } = useServices();
+
+  const onSubmit = () => {
+    console.log('[DEBUG:ui] Open Folder — Continue clicked');
+    toast.promise(editorSvc.grantFolderAccess(), {
+      loading: 'Granting folder access...',
+      success: 'Folder access granted! File references will now be resolved.',
+      error: 'Failed to grant folder access.',
+    });
+  };
+
+  return (
+    <ConfirmModal
+      title="Open Folder"
+      confirmText="Continue"
+      confirmDisabled={false}
+      onSubmit={onSubmit}
+    >
+      <div className="flex flex-col space-y-4 text-sm text-gray-700">
+        <p>
+          This will allow Studio to resolve local <code className="bg-gray-100 px-1 py-0.5 rounded text-pink-600">$ref</code> references
+          (e.g., Avro schemas, JSON schemas) relative to your project folder.
+        </p>
+        <p className="font-medium">You will be prompted in two steps:</p>
+        <ol className="list-decimal list-inside space-y-2 pl-2">
+          <li>
+            Select the <strong>root folder</strong> containing your AsyncAPI project files
+          </li>
+          <li>
+            Select the <strong>AsyncAPI file</strong> (<code className="bg-gray-100 px-1 py-0.5 rounded">.yaml</code>,{' '}
+            <code className="bg-gray-100 px-1 py-0.5 rounded">.yml</code>, or{' '}
+            <code className="bg-gray-100 px-1 py-0.5 rounded">.json</code>) within that folder
+          </li>
+        </ol>
+      </div>
+    </ConfirmModal>
+  );
+});
+
diff --git a/apps/studio/src/components/Modals/index.tsx b/apps/studio/src/components/Modals/index.tsx
index 048d4991b..750b2fc3e 100644
--- a/apps/studio/src/components/Modals/index.tsx
+++ b/apps/studio/src/components/Modals/index.tsx
@@ -9,5 +9,6 @@ export * from './ImportURLModal';
 export * from './ImportUUIDModal';
 
 export * from './NewFileModal';
+export * from './OpenFolderModal';
 export * from './RedirectedModal';
 export * from './ConfirmNewFileModal';
\ No newline at end of file
diff --git a/apps/studio/src/components/StudioWrapper.tsx b/apps/studio/src/components/StudioWrapper.tsx
index fbafbf474..6626da25a 100644
--- a/apps/studio/src/components/StudioWrapper.tsx
+++ b/apps/studio/src/components/StudioWrapper.tsx
@@ -1,5 +1,5 @@
 'use client'
-import { StrictMode, useEffect, useState } from 'react';
+import { StrictMode, useEffect, useState, useRef } from 'react';
 import { Provider as ModalsProvider } from '@ebay/nice-modal-react';
 
 import { createServices, Services, ServicesProvider } from '@/services';
@@ -10,29 +10,20 @@ import { driverObj } from '@/helpers/driver';
 
 function configureMonacoEnvironment() {
   if (typeof window !== 'undefined') {
-    const editorWorkerUrl = 'monaco-editor/esm/vs/editor/editor.worker';
-
     window.MonacoEnvironment = {
       getWorker(_, label) {
-        try {
-          switch (label) {
-          case 'editorWorkerService':
-            return new Worker(new URL(editorWorkerUrl, import.meta.url));
-          case 'json':
-            return new Worker(
-              new URL('monaco-editor/esm/vs/language/json/json.worker', import.meta.url),
-            );
-          case 'yaml':
-          case 'yml':
-            return new Worker(new URL('monaco-yaml/yaml.worker', import.meta.url));
-          default:
-            console.warn(`Unknown worker label: ${label}, falling back to editor worker`);
-            return new Worker(new URL(editorWorkerUrl, import.meta.url));
-          }
-        } catch (error) {
-          console.error(`Failed to create worker for ${label}:`, error);
-          // Fallback to editor worker
-          return new Worker(new URL(editorWorkerUrl, import.meta.url));
+        switch (label) {
+        case 'editorWorkerService':
+          return new Worker(new URL('monaco-editor/esm/vs/editor/editor.worker', import.meta.url));
+        case 'json':
+          return new Worker(
+            new URL('monaco-editor/esm/vs/language/json/json.worker', import.meta.url),
+          );
+        case 'yaml':
+        case 'yml':
+          return new Worker(new URL('monaco-yaml/yaml.worker', import.meta.url));
+        default:
+          throw new Error(`Unknown worker label: ${label}`);
         }
       },
     };
@@ -41,7 +32,15 @@ function configureMonacoEnvironment() {
 
 export default function StudioWrapper() {
   const [services, setServices] = useState<Services>();
+  const initializedRef = useRef(false);
+
   useEffect(() => {
+    // Prevent double initialization in React StrictMode
+    if (initializedRef.current) {
+      return;
+    }
+    initializedRef.current = true;
+
     const fetchData = async () => {
       // Configure Monaco environment BEFORE creating services
       configureMonacoEnvironment();
diff --git a/apps/studio/src/services/app.service.ts b/apps/studio/src/services/app.service.ts
index a9abb7640..386fa3b3d 100644
--- a/apps/studio/src/services/app.service.ts
+++ b/apps/studio/src/services/app.service.ts
@@ -52,6 +52,8 @@ export class ApplicationService extends AbstractService {
       return;
     }
 
+    console.log('[DEBUG:app] fetchResource', { url, base64: !!base64, share });
+
     const { updateFile } = filesState.getState();
     let content = '';
     if (url) {
@@ -79,8 +81,8 @@ export class ApplicationService extends AbstractService {
       language,
       source,
       from: from as 'url' | 'base64' | 'share',
+      stat: { mtime: Date.now() },
     });
-    await this.svcs.parserSvc.parse('asyncapi', content, { source });
   }
 
   private hidePreloader() {
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 8cdde7fd4..3b1e3851c 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -102,11 +102,84 @@ export class EditorService extends AbstractService {
     this.updateState({ content: converted, updateModel: true });
   }
 
+  async grantFolderAccess(): Promise<void> {
+    // 1. Ask user to pick the root folder
+    let directoryHandle: FileSystemDirectoryHandle;
+    try {
+      directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
+    } catch (err: any) {
+      // User cancelled — silently ignore
+      if (err?.name === 'AbortError') return;
+      throw err;
+    }
+
+    // 2. Ask user to pick the AsyncAPI file within that folder
+    toast.loading('Please select the AsyncAPI file within the folder...', { id: 'folder-access' });
+    let fileHandle: FileSystemFileHandle;
+    try {
+      const [handle] = await window.showOpenFilePicker({
+        types: [{ description: 'AsyncAPI files', accept: { 'text/*': ['.yaml', '.yml', '.json'] } }],
+        multiple: false,
+      });
+      fileHandle = handle;
+    } catch (err: any) {
+      toast.dismiss('folder-access');
+      if (err?.name === 'AbortError') return;
+      throw err;
+    }
+
+    // 3. Compute the relative path of the selected file within the folder
+    const pathParts = await directoryHandle.resolve(fileHandle);
+    if (!pathParts) {
+      toast.dismiss('folder-access');
+      toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
+      return;
+    }
+    const localPath = pathParts.join('/');
+
+    // 4. Read file content
+    const file = await fileHandle.getFile();
+    const content = await file.text();
+    const language = this.svcs.formatSvc.retrieveLangauge(content);
+
+    // 5. Update file state — parser subscription will re-parse automatically with the local resolver
+    console.log(
+      '[DEBUG:editor] grantFolderAccess — updating file state',
+      '\n  from: file',
+      '\n  source:', `${directoryHandle.name}/${localPath}`,
+      '\n  localPath:', localPath,
+      '\n  directoryHandle:', directoryHandle.name,
+    );
+    const { updateFile } = filesState.getState();
+    updateFile('asyncapi', {
+      content,
+      language,
+      from: 'file',
+      source: `${directoryHandle.name}/${localPath}`,
+      directoryHandle,
+      fileHandle,
+      localPath,
+      modified: false,
+      stat: { mtime: Date.now() },
+    });
+
+    // Update the editor model
+    if (this.editor) {
+      const model = this.editor.getModel();
+      if (model) model.setValue(content);
+    }
+
+    toast.dismiss('folder-access');
+    toast.success('Folder access granted! File references will now be resolved.');
+  }
+
   async importFromURL(url: string): Promise<void> {
     if (!url) {
       throw new Error('URL is required');
     }
 
+    console.log('[DEBUG:editor] importFromURL', url);
+
     // Update browser URL with ?url= parameter (no page reload)
     const currentUrl = window.location.href.split('?')[0];
     window.history.pushState({}, '', `${currentUrl}?url=${url}`);
@@ -123,11 +196,9 @@ export class EditorService extends AbstractService {
             source: url,
             from: 'url',
             language,
+            stat: { mtime: Date.now() },
           },
         });
-
-        // Parse with source for remote $refs resolution
-        await this.svcs.parserSvc.parse('asyncapi', text, { source: url });
       })
       .catch(err => {
         console.error(err);
@@ -143,20 +214,31 @@ export class EditorService extends AbstractService {
     if (!file) {
       return;
     }
-    
-    // Check if file is valid (only JSON and YAML are allowed currently) ----Change afterwards as per the requirement
-    if (
-      file.type !== 'application/json' &&
-      file.type !== 'application/x-yaml' &&
-      file.type !== 'application/yaml'
-    ) {
-      throw new Error('Invalid file type');
+
+    // Validate by extension — MIME types are unreliable across browsers
+    const allowedExtensions = ['json', 'yaml', 'yml', 'avsc'];
+    const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
+    if (!allowedExtensions.includes(ext)) {
+      throw new Error('Invalid file type. Only .json, .yaml, .yml, and .avsc files are supported.');
     }
 
+    console.log('[DEBUG:editor] importFile', file.name);
+
     const fileReader = new FileReader();
     fileReader.onload = fileLoadedEvent => {
       const content = fileLoadedEvent.target?.result;
-      this.updateState({ content: String(content), updateModel: true });
+      this.updateState({
+        content: String(content),
+        updateModel: true,
+        file: {
+          from: 'file',
+          source: undefined,
+          directoryHandle: undefined,
+          fileHandle: undefined,
+          localPath: undefined,
+          stat: { mtime: Date.now() },
+        },
+      });
     };
     fileReader.readAsText(file, 'UTF-8');
   }
@@ -303,7 +385,6 @@ export class EditorService extends AbstractService {
 
     const { updateFile } = filesState.getState();
     updateFile('asyncapi', {
-      from: 'storage',
       source, // Preserve the source URL
       modified: false,
     });
diff --git a/apps/studio/src/services/local-file-resolver.ts b/apps/studio/src/services/local-file-resolver.ts
new file mode 100644
index 000000000..7586edffc
--- /dev/null
+++ b/apps/studio/src/services/local-file-resolver.ts
@@ -0,0 +1,143 @@
+/**
+ * Local File Resolver for AsyncAPI Parser (Stage 2/3)
+ *
+ * Resolves local $ref paths by navigating the folder granted via the
+ * File System Access API (window.showDirectoryPicker).
+ */
+
+/**
+ * Normalise a relative reference path against the base file path.
+ *
+ * Examples:
+ *   normaliseRelativePath('asyncapi.yaml', 'apis/schema.avsc')  → 'apis/schema.avsc'
+ *   normaliseRelativePath('specs/api.yaml', '../schemas/user.avsc') → 'schemas/user.avsc'
+ *   normaliseRelativePath('specs/api.yaml', './types.json') → 'specs/types.json'
+ */
+export function normaliseRelativePath(basePath: string, relativePath: string): string {
+  // Start from the directory of the base file
+  const baseParts = basePath.split('/');
+  baseParts.pop(); // remove the filename, keep only directory segments
+
+  const refParts = relativePath.split('/');
+
+  for (const part of refParts) {
+    if (part === '..') {
+      baseParts.pop();
+    } else if (part !== '.') {
+      baseParts.push(part);
+    }
+  }
+
+  const resolved = baseParts.join('/');
+  console.log('[DEBUG:resolver] normaliseRelativePath', { basePath, relativePath, resolved });
+  return resolved;
+}
+
+/**
+ * Navigate the directory tree to find the file at `filePath` (relative to `directoryHandle`).
+ * Returns the FileSystemFileHandle for the target file.
+ *
+ * Throws descriptive errors if intermediate directories or the final file are not found.
+ */
+export async function getFileHandleFromPath(
+  directoryHandle: FileSystemDirectoryHandle,
+  filePath: string,
+): Promise<FileSystemFileHandle> {
+  const parts = filePath.split('/').filter(Boolean);
+  const fileName = parts.pop();
+
+  if (!fileName) {
+    throw new Error(`Invalid file path: "${filePath}"`);
+  }
+
+  let currentDir = directoryHandle;
+
+  for (const dirName of parts) {
+    try {
+      console.log('[DEBUG:resolver] getFileHandleFromPath navigating to dir:', dirName);
+      currentDir = await currentDir.getDirectoryHandle(dirName);
+    } catch {
+      throw new Error(
+        `Directory not found: "${dirName}" in path "${filePath}". ` +
+        'Make sure the selected folder contains this directory.',
+      );
+    }
+  }
+
+  try {
+    console.log('[DEBUG:resolver] getFileHandleFromPath getting file:', fileName);
+    return await currentDir.getFileHandle(fileName);
+  } catch {
+    throw new Error(
+      `File not found: "${fileName}" in path "${filePath}". ` +
+      'Make sure the file exists in the selected folder.',
+    );
+  }
+}
+
+export interface LocalFileResolverOptions {
+  directoryHandle: FileSystemDirectoryHandle;
+  /** Relative path of the main AsyncAPI file within the folder, e.g. "asyncapi.yaml" or "specs/api.yaml" */
+  basePath: string;
+}
+
+/**
+ * Extract a usable path string from a urijs Uri object or a plain string.
+ */
+function extractPath(uri: any): string {
+  if (typeof uri === 'string') return uri;
+  // urijs Uri objects expose .path() as a method
+  if (typeof uri.path === 'function') return uri.path();
+  // fallback: toString() and strip protocol
+  return String(uri).replace(/^file:\/\/\/?/, '');
+}
+
+/**
+ * Returns a resolver object compatible with the AsyncAPI parser's
+ * `__unstable.resolver.resolvers` option.
+ *
+ * The resolver uses `schema: 'file'` so the parser dispatches `file://` URIs
+ * to it, and `order: 1` so it runs before the default Node.js file resolver
+ * (which would fail in the browser with "readFile is not a function").
+ */
+export function createLocalFileResolver(options: LocalFileResolverOptions) {
+  const { directoryHandle, basePath } = options;
+  // The source passed to the parser is `folderName/localPath` (e.g. "apis/asyncapi.yml").
+  // The parser resolves $refs relative to that source, producing paths like
+  // "apis/schemas/User.avsc".  We need to strip the folder name prefix to get
+  // the path relative to the directoryHandle (e.g. "schemas/User.avsc").
+  const folderPrefix = directoryHandle.name + '/';
+
+  console.log('[DEBUG:resolver] createLocalFileResolver created', { basePath, folderName: directoryHandle.name, folderPrefix });
+
+  return {
+    schema: 'file' as const,
+    order: 1,
+
+    canRead(uri: any) {
+      const p = extractPath(uri);
+      console.log('[DEBUG:resolver] canRead called for', p, '(raw uri:', String(uri), ')');
+      return true; // Accept all file:// URIs — we handle everything in this folder
+    },
+
+    async read(uri: any): Promise<string> {
+      const rawPath = extractPath(uri);
+      console.log('[DEBUG:resolver] read() called for', rawPath, '(raw uri:', String(uri), ')');
+
+      // Strip leading slashes and the folder name prefix to get a path
+      // relative to the directoryHandle.
+      let relativePath = rawPath.replace(/^\/+/, '');
+      if (relativePath.startsWith(folderPrefix)) {
+        relativePath = relativePath.slice(folderPrefix.length);
+      }
+
+      console.log('[DEBUG:resolver] read() relativePath:', relativePath);
+      const fileHandle = await getFileHandleFromPath(directoryHandle, relativePath);
+      const file = await fileHandle.getFile();
+      const content = await file.text();
+      console.log('[DEBUG:resolver] read() success for', relativePath, `(${content.length} chars)`);
+      return content;
+    },
+  };
+}
+
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index 3bd59c4da..37f7e9ff2 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -8,6 +8,7 @@ import { untilde } from '@asyncapi/parser/cjs/utils';
 
 import { isDeepEqual } from '@/helpers';
 import { filesState, documentsState, settingsState } from '@/state';
+import { createLocalFileResolver } from './local-file-resolver';
 
 import type { Diagnostic, ParseOptions } from '@asyncapi/parser';
 import type { DocumentDiagnostics } from '@/state/documents.state';
@@ -16,6 +17,8 @@ import { getLocationForJsonPath, parseWithPointers } from '@stoplight/yaml';
 
 export class ParserService extends AbstractService {
   private parser!: Parser;
+  private unsubscribeFiles?: () => void;
+  private unsubscribeSettings?: () => void;
 
   override async onInit() {
     this.parser = new Parser({
@@ -37,11 +40,41 @@ export class ParserService extends AbstractService {
     await this.parseSavedDocuments();
   }
 
+  destroy() {
+    // Clean up subscriptions when service is destroyed
+    this.unsubscribeFiles?.();
+    this.unsubscribeSettings?.();
+  }
+
   async parse(uri: string, spec: string, options: ParseOptions = {}): Promise<void> {
     if (uri !== 'asyncapi' && !options.source) {
       options.source = uri;
     }
 
+    // Inject local file resolver when the file was opened from local disk with folder access
+    const file = filesState.getState().files[String(uri)];
+    const useLocalResolver = !!(file?.from === 'file' && file.directoryHandle && file.localPath);
+    console.log(
+      '[DEBUG:parser] parse()', uri,
+      '\n  file.from:', file?.from,
+      '\n  file.source:', file?.source,
+      '\n  file.localPath:', file?.localPath,
+      '\n  hasDirectoryHandle:', !!file?.directoryHandle,
+      '\n  options.source:', options.source,
+      '\n  → resolver:', useLocalResolver ? 'LOCAL FILE RESOLVER' : 'default (remote/HTTP)',
+    );
+    if (useLocalResolver && file.directoryHandle && file.localPath) {
+      const resolver = createLocalFileResolver({
+        directoryHandle: file.directoryHandle,
+        basePath: file.localPath,
+      });
+      (options as any).__unstable = {
+        resolver: {
+          resolvers: [resolver],
+        },
+      };
+    }
+
     let diagnostics: Diagnostic[] = [];
     try {
       const { document, diagnostics: _diagnostics, extras } = await this.parser.parse(spec, options);
@@ -124,10 +157,15 @@ export class ParserService extends AbstractService {
   private updateDocument = documentsState.getState().updateDocument;
 
   private createDiagnostics(diagnostics: Diagnostic[]) {
-    // map messages of invalid ref to file
+    // Map unresolvable local file ref errors to a clear, actionable message
     diagnostics.forEach(diagnostic => {
-      if (diagnostic.code === 'invalid-ref' && diagnostic.message.endsWith('readFile is not a function')) {
-        diagnostic.message = 'File references are not yet supported in Studio';
+      if (
+        diagnostic.code === 'invalid-ref' &&
+        (diagnostic.message.endsWith('readFile is not a function') ||
+          diagnostic.message.includes('File references are not yet supported'))
+      ) {
+        diagnostic.message =
+          'Local file reference detected. Click Import → Grant Folder Access to resolve this reference.';
       }
     });
     
@@ -162,20 +200,48 @@ export class ParserService extends AbstractService {
   }
 
   private subscribeToFiles() {
-    filesState.subscribe((state, prevState) => {
+    // Unsubscribe from previous subscription if it exists
+    if (this.unsubscribeFiles) {
+      console.log('[DEBUG:parser] subscribeToFiles - cleaning up previous subscription');
+      this.unsubscribeFiles();
+    }
+
+    this.unsubscribeFiles = filesState.subscribe((state, prevState) => {
       const newFiles = state.files;
       const oldFiles = prevState.files;
 
       Object.entries(newFiles).forEach(([uri, file]) => {
         const oldFile = oldFiles[String(uri)];
         if (file === oldFile) return;
+
+        // Skip cosmetic-only changes (from, modified, language, name).
+        // Re-parse only when content, resolver configuration, or the explicit
+        // freshness timestamp (stat.mtime) changed.
+        const contentChanged = file.content !== oldFile?.content;
+        const sourceChanged = file.source !== oldFile?.source;
+        const directoryHandleChanged = file.directoryHandle !== oldFile?.directoryHandle;
+        const localPathChanged = file.localPath !== oldFile?.localPath;
+        const mtimeChanged = file.stat?.mtime !== oldFile?.stat?.mtime;
+
+        console.log('[DEBUG:parser] subscribeToFiles', uri, { contentChanged, sourceChanged, directoryHandleChanged, localPathChanged, mtimeChanged });
+
+        if (!contentChanged && !sourceChanged && !directoryHandleChanged && !localPathChanged && !mtimeChanged) {
+          return;
+        }
+
         this.parse(uri, file.content, { source: file.source }).catch(console.error);
       });
     });
   }
 
   private subscribeToSettings() {
-    settingsState.subscribe((state, prevState) => {
+    // Unsubscribe from previous subscription if it exists
+    if (this.unsubscribeSettings) {
+      console.log('[DEBUG:parser] subscribeToSettings - cleaning up previous subscription');
+      this.unsubscribeSettings();
+    }
+
+    this.unsubscribeSettings = settingsState.subscribe((state, prevState) => {
       if (isDeepEqual(state.governance, prevState.governance)) return;
 
       const { files } = filesState.getState();
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index a3f6cbc63..431945ce4 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -243,11 +243,17 @@ export type File = {
   uri: string;
   name: string;
   content: string;
-  from: 'storage' | 'url' | 'base64' | 'share';
+  from: 'storage' | 'url' | 'base64' | 'share' | 'file';
   source?: string;
   language: 'json' | 'yaml';
   modified: boolean;
   stat?: FileStat;
+  /** File System Access API handle for the specific file (Stage 4: save-back) */
+  fileHandle?: FileSystemFileHandle;
+  /** File System Access API handle for the containing folder (Stage 2/3: local $ref resolution) */
+  directoryHandle?: FileSystemDirectoryHandle;
+  /** Relative path of this file within the directoryHandle folder, e.g. "asyncapi.yaml" or "specs/api.yaml" */
+  localPath?: string;
 }
 
 export type FilesState = {
@@ -258,7 +264,7 @@ export type FilesActions = {
   updateFile: (uri: string, file: Partial<File>) => void;
 }
 
-export const filesState = create<FilesState & FilesActions>(set => ({
+export const filesState = create<FilesState & FilesActions>((set, get) => ({
   files: {
     asyncapi: {
       uri: 'asyncapi',
@@ -274,7 +280,16 @@ export const filesState = create<FilesState & FilesActions>(set => ({
     }
   },
   updateFile(uri: string, file: Partial<File>) {
+    const before = get().files[String(uri)];
+    const logBefore = before
+      ? { from: before.from, source: before.source, localPath: before.localPath, hasDirectoryHandle: !!before.directoryHandle, hasFileHandle: !!before.fileHandle }
+      : '(new file)';
+    const logPatch = { from: file.from, source: file.source, localPath: file.localPath, hasDirectoryHandle: !!file.directoryHandle, hasFileHandle: !!file.fileHandle };
+    console.log('[DEBUG:filesState] updateFile ▶', uri, '\n  before:', logBefore, '\n  patch: ', logPatch);
     set(state => ({ files: { ...state.files, [String(uri)]: { ...state.files[String(uri)] || {}, ...file } } }));
+    const after = get().files[String(uri)];
+    const logAfter = { from: after.from, source: after.source, localPath: after.localPath, hasDirectoryHandle: !!after.directoryHandle, hasFileHandle: !!after.fileHandle };
+    console.log('[DEBUG:filesState] updateFile ◀', uri, '\n  after: ', logAfter);
   }
 }));
 

From 0d9189c220db133004f9606e3bec69ea5f839638 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Tue, 3 Mar 2026 12:05:18 +0100
Subject: [PATCH 04/23] url navigation removal

---
 .../studio/src/services/navigation.service.ts | 56 +++++++++++++
 .../services/tests/navigation.service.test.ts | 79 +++++++++++++++++--
 2 files changed, 127 insertions(+), 8 deletions(-)

diff --git a/apps/studio/src/services/navigation.service.ts b/apps/studio/src/services/navigation.service.ts
index 5808c4c6c..2e4c5976e 100644
--- a/apps/studio/src/services/navigation.service.ts
+++ b/apps/studio/src/services/navigation.service.ts
@@ -1,8 +1,15 @@
 import { AbstractService } from './abstract.service';
+import { filesState } from '@/state';
 
 import type React from 'react';
 
 export class NavigationService extends AbstractService {
+  private unsubscribeFiles?: () => void;
+
+  override onInit() {
+    this.subscribeToFiles();
+  }
+
   override async afterAppInit() {
     try {
       await this.scrollToHash();
@@ -106,4 +113,53 @@ export class NavigationService extends AbstractService {
     window.history.pushState({}, '', hash);
     window.dispatchEvent(new HashChangeEvent('hashchange'));
   }
+
+  destroy() {
+    this.unsubscribeFiles?.();
+  }
+
+  private subscribeToFiles() {
+    this.unsubscribeFiles?.();
+
+    this.unsubscribeFiles = filesState.subscribe((state, prevState) => {
+      const currentFile = state.files['asyncapi'];
+      const previousFile = prevState.files['asyncapi'];
+
+      if (!currentFile || !previousFile) {
+        return;
+      }
+
+      if (currentFile.from === previousFile.from) {
+        return;
+      }
+
+      if (previousFile.from === 'url' && currentFile.from !== 'url') {
+        this.removeRemoteUrlParams();
+      }
+    });
+  }
+
+  private removeRemoteUrlParams() {
+    const [baseWithPath, hash] = window.location.href.split('#');
+    const [base, query] = baseWithPath.split('?');
+
+    if (!query) {
+      return;
+    }
+
+    const segments = query.split('&').filter(Boolean);
+    const keptSegments = segments.filter((part) => {
+      return part !== 'url' &&
+        !part.startsWith('url=') &&
+        part !== 'load' &&
+        !part.startsWith('load=');
+    });
+
+    const nextUrl = keptSegments.length > 0
+      ? `${base}?${keptSegments.join('&')}`
+      : base;
+
+    const urlWithHash = hash ? `${nextUrl}#${hash}` : nextUrl;
+    window.history.replaceState({}, '', urlWithHash);
+  }
 }
diff --git a/apps/studio/src/services/tests/navigation.service.test.ts b/apps/studio/src/services/tests/navigation.service.test.ts
index 9078a211c..2e62040df 100644
--- a/apps/studio/src/services/tests/navigation.service.test.ts
+++ b/apps/studio/src/services/tests/navigation.service.test.ts
@@ -1,4 +1,5 @@
 import { createServices } from '../';
+import { filesState } from '@/state';
 
 import type { NavigationService } from '../navigation.service';
 
@@ -10,15 +11,26 @@ describe('NavigationService', () => {
     navigationSvc = services.navigationSvc;
   });
 
+  afterAll(() => {
+    navigationSvc.destroy();
+  });
+
+  afterEach(() => {
+    window.history.replaceState({}, '', '/');
+  });
+
   function updateLocation(search: string) {
-    const location = {
-      ...window.location,
-      search,
-    };
-    Object.defineProperty(window, 'location', {
-      writable: true,
-      value: location,
-    });
+    window.history.replaceState({}, '', `/${search}`);
+  }
+
+  function updateHref(pathAndQueryAndHash: string) {
+    window.history.replaceState({}, '', pathAndQueryAndHash);
+  }
+
+  function transitionSource(from: 'storage' | 'url' | 'base64' | 'share' | 'file', to: 'storage' | 'url' | 'base64' | 'share' | 'file') {
+    const { updateFile } = filesState.getState();
+    updateFile('asyncapi', { from, stat: { mtime: Date.now() } });
+    updateFile('asyncapi', { from: to, stat: { mtime: Date.now() + 1 } });
   }
 
   describe('.getUrlParameters() - checking readOnly parameter', () => {
@@ -46,4 +58,55 @@ describe('NavigationService', () => {
       expect(result.readOnly).toEqual(false);
     });
   });
+
+  describe('query cleanup on source transitions', () => {
+    test('removes `url` when leaving remote source', () => {
+      updateHref('/?url=https://a.com/spec.yaml&readOnly=true');
+
+      transitionSource('url', 'file');
+
+      expect(window.location.search).toEqual('?readOnly=true');
+    });
+
+    test('removes legacy `load` when leaving remote source', () => {
+      updateHref('/?load=https://a.com/spec.yaml&previewServer=x');
+
+      transitionSource('url', 'base64');
+
+      expect(window.location.search).toEqual('?previewServer=x');
+    });
+
+    test('removes both `url` and `load` if both are present', () => {
+      updateHref('/?url=a&load=b&x=1');
+
+      transitionSource('url', 'share');
+
+      expect(window.location.search).toEqual('?x=1');
+    });
+
+    test('preserves hash when cleaning query params', () => {
+      updateHref('/?url=a&x=1#section-2');
+
+      transitionSource('url', 'file');
+
+      expect(window.location.search).toEqual('?x=1');
+      expect(window.location.hash).toEqual('#section-2');
+    });
+
+    test('does not cleanup when source remains url', () => {
+      updateHref('/?url=a&x=1');
+
+      transitionSource('url', 'url');
+
+      expect(window.location.search).toEqual('?url=a&x=1');
+    });
+
+    test('does not cleanup on non-url transitions', () => {
+      updateHref('/?url=a&x=1');
+
+      transitionSource('file', 'share');
+
+      expect(window.location.search).toEqual('?url=a&x=1');
+    });
+  });
 });

From 2c1577230cf604d0c8bb635f0405b566f9379b44 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Tue, 3 Mar 2026 12:05:41 +0100
Subject: [PATCH 05/23] fix: buttons nested inside buttons

---
 apps/studio/src/components/Editor/ConvertDropdown.tsx  | 4 ++--
 apps/studio/src/components/Editor/GenerateDropdown.tsx | 6 +++---
 apps/studio/src/components/Editor/SaveDropdown.tsx     | 6 +++---
 3 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/studio/src/components/Editor/ConvertDropdown.tsx b/apps/studio/src/components/Editor/ConvertDropdown.tsx
index f9961060e..076c413c6 100644
--- a/apps/studio/src/components/Editor/ConvertDropdown.tsx
+++ b/apps/studio/src/components/Editor/ConvertDropdown.tsx
@@ -19,9 +19,9 @@ export const ConvertDropdown: React.FC = () => {
     <Dropdown
       opener={
         <Tooltip content="Convert" placement="top" hideOnClick={true}>
-          <button className="bg-inherit">
+          <div className="bg-inherit">
             <FaFileExport />
-          </button>
+          </div>
         </Tooltip>
       }
       buttonHoverClassName="text-gray-500 hover:text-white"
diff --git a/apps/studio/src/components/Editor/GenerateDropdown.tsx b/apps/studio/src/components/Editor/GenerateDropdown.tsx
index 11954ba78..ebfb5de57 100644
--- a/apps/studio/src/components/Editor/GenerateDropdown.tsx
+++ b/apps/studio/src/components/Editor/GenerateDropdown.tsx
@@ -18,9 +18,9 @@ export const GenerateDropdown: React.FC = () => {
     <Dropdown
       opener={
         <Tooltip content="Generate" placement="top" hideOnClick={true}>
-          <button className="bg-inherit">
+          <div className="bg-inherit">
             <FaCode />
-          </button>
+          </div>
         </Tooltip>
       }
       buttonHoverClassName="text-gray-500 hover:text-white"
@@ -65,4 +65,4 @@ export const GenerateDropdown: React.FC = () => {
       </ul>
     </Dropdown>
   );
-};
\ No newline at end of file
+};
diff --git a/apps/studio/src/components/Editor/SaveDropdown.tsx b/apps/studio/src/components/Editor/SaveDropdown.tsx
index f26142df8..ae34daa65 100644
--- a/apps/studio/src/components/Editor/SaveDropdown.tsx
+++ b/apps/studio/src/components/Editor/SaveDropdown.tsx
@@ -17,9 +17,9 @@ export const SaveDropdown: React.FC = () => {
     <Dropdown
       opener={
         <Tooltip content="Save" placement="top" hideOnClick={true}>
-          <button className="bg-inherit">
+          <div className="bg-inherit">
             <FaSave />
-          </button>
+          </div>
         </Tooltip>
       }
       buttonHoverClassName="text-gray-500 hover:text-white"
@@ -98,4 +98,4 @@ export const SaveDropdown: React.FC = () => {
       </ul>
     </Dropdown>
   );
-};
\ No newline at end of file
+};

From fadc475f8d5d74dfa2816c77f77675376d60f495 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Tue, 3 Mar 2026 14:56:27 +0100
Subject: [PATCH 06/23] filetree frist working draft

---
 .../src/components/Editor/ConvertDropdown.tsx |   3 +-
 .../src/components/Editor/EditorDropdown.tsx  |   3 +-
 .../components/Editor/GenerateDropdown.tsx    |   3 +-
 .../src/components/Editor/MonacoWrapper.tsx   |   6 +-
 .../src/components/Editor/SaveDropdown.tsx    |   3 +-
 apps/studio/src/components/FileTreeView.tsx   | 274 +++++++++++++++
 apps/studio/src/components/Navigation.tsx     |  19 +-
 apps/studio/src/components/Navigationv3.tsx   |   9 +-
 .../src/components/Terminal/ProblemsTab.tsx   |  15 +-
 .../src/components/Terminal/TerminalInfo.tsx  |   4 +
 apps/studio/src/services/app.service.ts       |  39 ++-
 apps/studio/src/services/editor.service.tsx   | 328 ++++++++++++++----
 .../src/services/local-file-resolver.ts       |  17 +-
 apps/studio/src/services/parser.service.ts    | 150 ++++++--
 apps/studio/src/state/documents.state.ts      |  32 +-
 apps/studio/src/state/files.state.ts          |  85 ++++-
 16 files changed, 849 insertions(+), 141 deletions(-)
 create mode 100644 apps/studio/src/components/FileTreeView.tsx

diff --git a/apps/studio/src/components/Editor/ConvertDropdown.tsx b/apps/studio/src/components/Editor/ConvertDropdown.tsx
index 076c413c6..b5480b576 100644
--- a/apps/studio/src/components/Editor/ConvertDropdown.tsx
+++ b/apps/studio/src/components/Editor/ConvertDropdown.tsx
@@ -11,7 +11,7 @@ import { useDocumentsState, useFilesState } from '../../state';
 export const ConvertDropdown: React.FC = () => {
   const { editorSvc } = useServices();
   const isInvalidDocument = !useDocumentsState(state => 
-    state.documents['asyncapi'].valid
+    state.documents['asyncapi']?.valid
   );
   const language = useFilesState(state => state.files['asyncapi'].language);
       
@@ -78,3 +78,4 @@ export const ConvertDropdown: React.FC = () => {
   );
 }
 
+
diff --git a/apps/studio/src/components/Editor/EditorDropdown.tsx b/apps/studio/src/components/Editor/EditorDropdown.tsx
index 7aa63f0ac..327d5e559 100644
--- a/apps/studio/src/components/Editor/EditorDropdown.tsx
+++ b/apps/studio/src/components/Editor/EditorDropdown.tsx
@@ -21,7 +21,7 @@ interface EditorDropdownProps {}
 export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () => {
   const { editorSvc } = useServices();
   const isInvalidDocument = !useDocumentsState(state => {
-    return state.documents['asyncapi'].valid
+    return state.documents['asyncapi']?.valid
   });
   const language = useFilesState(state => state.files['asyncapi'].language);
 
@@ -315,3 +315,4 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
     </Dropdown>
   );
 };
+
diff --git a/apps/studio/src/components/Editor/GenerateDropdown.tsx b/apps/studio/src/components/Editor/GenerateDropdown.tsx
index ebfb5de57..f045204bc 100644
--- a/apps/studio/src/components/Editor/GenerateDropdown.tsx
+++ b/apps/studio/src/components/Editor/GenerateDropdown.tsx
@@ -10,7 +10,7 @@ import { useServices } from '@/services';
 
 export const GenerateDropdown: React.FC = () => {
   const isInvalidDocument = !useDocumentsState(state => 
-    state.documents['asyncapi'].valid
+    state.documents['asyncapi']?.valid
   );
   const { editorSvc } = useServices();
 
@@ -66,3 +66,4 @@ export const GenerateDropdown: React.FC = () => {
     </Dropdown>
   );
 };
+
diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index c235e5f57..46010d60c 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -14,6 +14,9 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
   const { editorSvc } = useServices();
   const { autoSaving, savingDelay } = useSettingsState(state => state.editor);
   const file = useFilesState(state => state.files['asyncapi']);
+  if (!file) {
+    return null;
+  }
 
   const onChange = useMemo(() => {
     return debounce((v: string) => {
@@ -27,8 +30,9 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
 
   return (
     <MonacoEditor
+      key={file.uri}
       language={file.language}
-      defaultValue={file.content}
+      value={file.content}
       theme="asyncapi-theme"
       onMount={editorSvc.onDidCreate.bind(editorSvc)}
       onChange={onChange}
diff --git a/apps/studio/src/components/Editor/SaveDropdown.tsx b/apps/studio/src/components/Editor/SaveDropdown.tsx
index ae34daa65..53bc6e788 100644
--- a/apps/studio/src/components/Editor/SaveDropdown.tsx
+++ b/apps/studio/src/components/Editor/SaveDropdown.tsx
@@ -9,7 +9,7 @@ import { useDocumentsState, useFilesState } from '../../state';
 export const SaveDropdown: React.FC = () => {
   const { editorSvc } = useServices();
   const isInvalidDocument = !useDocumentsState(state => 
-    state.documents['asyncapi'].valid
+    state.documents['asyncapi']?.valid
   );
   const language = useFilesState(state => state.files['asyncapi'].language);
 
@@ -99,3 +99,4 @@ export const SaveDropdown: React.FC = () => {
     </Dropdown>
   );
 };
+
diff --git a/apps/studio/src/components/FileTreeView.tsx b/apps/studio/src/components/FileTreeView.tsx
new file mode 100644
index 000000000..c4769355b
--- /dev/null
+++ b/apps/studio/src/components/FileTreeView.tsx
@@ -0,0 +1,274 @@
+import React, { useMemo, useState } from 'react';
+import { VscChevronDown, VscChevronRight, VscFile, VscFolder, VscFolderOpened, VscGlobe } from 'react-icons/vsc';
+
+import { useServices } from '@/services';
+import { useFilesState } from '@/state';
+
+type TreeNode = {
+  name: string;
+  path: string;
+  type: 'file' | 'folder';
+  uri?: string;
+  title?: string;
+  isRemoteGroup?: boolean;
+  children?: TreeNode[];
+};
+
+type TreeEntry = {
+  key: string;
+  path: string;
+  uri: string;
+  title?: string;
+};
+
+function buildTree(entries: TreeEntry[]): TreeNode[] {
+  type RawNode = TreeNode & { childrenMap: Record<string, RawNode> };
+  const root: Record<string, RawNode> = {};
+
+  for (const entry of entries) {
+    const parts = entry.path.split('/').filter(Boolean);
+    if (parts.length === 0) continue;
+
+    let level = root;
+    let currentPath = '';
+    parts.forEach((part, index) => {
+      currentPath = currentPath ? `${currentPath}/${part}` : part;
+      const isFile = index === parts.length - 1;
+      if (!level[part]) {
+        level[part] = {
+          name: part,
+          path: `${entry.key}:${currentPath}`,
+          type: isFile ? 'file' : 'folder',
+          uri: isFile ? entry.uri : undefined,
+          title: isFile ? entry.title : undefined,
+          children: isFile ? undefined : [],
+          childrenMap: {},
+        };
+      }
+      if (!isFile) {
+        level[part].type = 'folder';
+        level = level[part].childrenMap;
+      }
+    });
+  }
+
+  const normalize = (map: Record<string, RawNode>): TreeNode[] =>
+    Object.values(map)
+      .map((node) => {
+        const { childrenMap, ...rest } = node;
+        return {
+          ...rest,
+          children: Object.keys(childrenMap).length > 0 ? normalize(childrenMap) : undefined,
+        };
+      })
+      .sort((a, b) => {
+        if (a.type !== b.type) return a.type === 'folder' ? -1 : 1;
+        return a.name.localeCompare(b.name);
+      });
+
+  return normalize(root);
+}
+
+function getFileTypeColor(name: string): string {
+  const lower = name.toLowerCase();
+  if (lower.endsWith('.yaml') || lower.endsWith('.yml')) return 'text-blue-400';
+  if (lower.endsWith('.json')) return 'text-yellow-400';
+  if (lower.endsWith('.avsc')) return 'text-green-400';
+  return 'text-gray-300';
+}
+
+function truncateExternalUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    const fileName = parts[parts.length - 1] || parsed.host;
+    return `${parsed.protocol}//.../${fileName}`;
+  } catch {
+    return url.length > 32 ? `${url.slice(0, 16)}...${url.slice(-12)}` : url;
+  }
+}
+
+function formatRemoteGroupLabel(url: string): string {
+  return url;
+}
+
+export const FileTreeView: React.FC = () => {
+  const { editorSvc } = useServices();
+  const [collapsed, setCollapsed] = useState(false);
+  const [expandedFolders, setExpandedFolders] = useState<Record<string, boolean>>({});
+
+  const { files, activeFileUri, fileTreeMode, projectRoot, fileTreeLoading } = useFilesState((state) => ({
+    files: state.files,
+    activeFileUri: state.activeFileUri,
+    fileTreeMode: state.fileTreeMode,
+    projectRoot: state.projectRoot,
+    fileTreeLoading: state.fileTreeLoading,
+  }));
+
+  const projectFiles = useMemo(
+    () => Object.entries(files).filter(([uri]) => uri !== 'asyncapi').map(([, file]) => file).sort((a, b) => a.uri.localeCompare(b.uri)),
+    [files],
+  );
+
+  const activeFile = useMemo(() => files['asyncapi'], [files]);
+
+  const localTree = useMemo(
+    () =>
+      buildTree(
+        projectFiles.map((file) => ({
+          key: 'local',
+          path: file.uri,
+          uri: file.uri,
+        })),
+      ),
+    [projectFiles],
+  );
+
+  const remoteTree = useMemo(() => {
+    const remoteFiles = projectFiles.filter((file) => /^https?:\/\//.test(file.uri));
+    const mainRemote = remoteFiles.find((file) => file.isAsyncApiDocument) || remoteFiles[0];
+    const baseDir = (() => {
+      if (!mainRemote) return undefined;
+      try {
+        return new URL('.', mainRemote.uri).href;
+      } catch {
+        return undefined;
+      }
+    })();
+
+    const baseEntries: TreeEntry[] = [];
+    const groups = new Map<string, TreeNode>();
+
+    for (const file of remoteFiles) {
+      if (baseDir && file.uri.startsWith(baseDir)) {
+        baseEntries.push({
+          key: 'remote-base',
+          path: file.uri.slice(baseDir.length),
+          uri: file.uri,
+        });
+        continue;
+      }
+
+      let baseUrl = file.uri;
+      let fileName = file.uri;
+
+      try {
+        const parsed = new URL(file.uri);
+        baseUrl = new URL('.', parsed.href).href;
+        const parts = parsed.pathname.split('/').filter(Boolean);
+        fileName = parts[parts.length - 1] || parsed.host;
+      } catch {
+        fileName = truncateExternalUrl(file.uri);
+      }
+
+      const groupPath = `remote-group:${baseUrl}`;
+      if (!groups.has(baseUrl)) {
+        groups.set(baseUrl, {
+          name: formatRemoteGroupLabel(baseUrl),
+          path: groupPath,
+          type: 'folder',
+          title: baseUrl,
+          isRemoteGroup: true,
+          children: [],
+        });
+      }
+
+      const group = groups.get(baseUrl);
+      group?.children?.push({
+        name: fileName,
+        path: `${groupPath}/${fileName}`,
+        type: 'file',
+        uri: file.uri,
+        title: file.uri,
+      });
+    }
+
+    const groupedNodes = Array.from(groups.values())
+      .map((group) => ({
+        ...group,
+        children: group.children?.slice().sort((a, b) => a.name.localeCompare(b.name)),
+      }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+    const baseNodes = buildTree(baseEntries);
+    const baseFolders = baseNodes.filter((node) => node.type === 'folder');
+    const baseFiles = baseNodes.filter((node) => node.type === 'file');
+
+    return [...groupedNodes, ...baseFolders, ...baseFiles];
+  }, [projectFiles]);
+
+  const renderNode = (node: TreeNode) => {
+    if (node.type === 'folder') {
+      const isExpanded = expandedFolders[node.path] ?? true;
+      const isRemoteGroup = !!node.isRemoteGroup || node.path.startsWith('remote-group:');
+      return (
+        <div key={node.path}>
+          <button
+            type="button"
+            className="w-full flex items-center px-2 py-1 text-left text-xs text-gray-200 hover:bg-gray-900"
+            onClick={() => setExpandedFolders((prev) => ({ ...prev, [node.path]: !isExpanded }))}
+            title={isRemoteGroup ? node.title : undefined}
+          >
+            {isExpanded ? <VscChevronDown className="mr-1" /> : <VscChevronRight className="mr-1" />}
+            {isRemoteGroup ? (
+              <VscGlobe className="mr-1 text-blue-400" />
+            ) : (
+              <>{isExpanded ? <VscFolderOpened className="mr-1 text-yellow-400" /> : <VscFolder className="mr-1 text-yellow-400" />}</>
+            )}
+            <span className="truncate">{node.name}</span>
+          </button>
+          {isExpanded && node.children && <div className="pl-3 border-l border-gray-700">{node.children.map((child) => renderNode(child))}</div>}
+        </div>
+      );
+    }
+
+    const fileUri = node.uri || node.path;
+    const isActive = activeFileUri === fileUri || activeFile?.uri === fileUri;
+    return (
+      <button
+        key={node.path}
+        type="button"
+        disabled={fileTreeLoading}
+        onClick={() => editorSvc.switchToFile(fileUri)}
+        className={`w-full flex items-center px-2 py-1 text-left text-xs ${
+          isActive ? 'bg-pink-900/40 border-l-2 border-pink-500 text-white' : 'text-gray-200 hover:bg-gray-900'
+        } ${fileTreeLoading ? 'opacity-50 cursor-not-allowed' : ''}`}
+        title={node.title}
+      >
+        <VscFile className={`mr-1 ${getFileTypeColor(node.name)}`} />
+        <span className="truncate">{node.name}</span>
+      </button>
+    );
+  };
+
+  if (fileTreeMode === 'none') {
+    return null;
+  }
+
+  const treeNodes = fileTreeMode === 'local' ? localTree : remoteTree;
+
+  return (
+    <div className="mb-4 border border-gray-700 bg-gray-800 rounded">
+      <button
+        type="button"
+        className="w-full flex items-center justify-between px-2 py-2 text-left text-white text-sm border-b border-gray-700"
+        onClick={() => setCollapsed((prev) => !prev)}
+      >
+        <span>
+          {fileTreeMode === 'local' ? 'Local Files' : 'Remote Files'}
+          {projectRoot ? ` • ${projectRoot}` : ''}
+        </span>
+        {collapsed ? <VscChevronRight /> : <VscChevronDown />}
+      </button>
+      {!collapsed && (
+        <div className="max-h-64 overflow-auto">
+          {projectFiles.length === 0 && <div className="px-2 py-3 text-xs text-gray-400">No project files available.</div>}
+          {projectFiles.length > 0 && <div className="py-1">{treeNodes.map((node) => renderNode(node))}</div>}
+          {fileTreeLoading && <div className="px-2 py-2 text-xs text-gray-400">Loading file...</div>}
+          {activeFile && activeFile.isAsyncApiDocument === false && (
+            <div className="px-2 py-2 text-xs text-gray-400 border-t border-gray-700">Referenced file (not an AsyncAPI document)</div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/apps/studio/src/components/Navigation.tsx b/apps/studio/src/components/Navigation.tsx
index ba98c9f5b..8ceb9a292 100644
--- a/apps/studio/src/components/Navigation.tsx
+++ b/apps/studio/src/components/Navigation.tsx
@@ -5,6 +5,7 @@ import React, { useEffect, useState } from 'react';
 import { useServices } from '@/services';
 import { useDocumentsState, useFilesState } from '@/state';
 import { NAVIGATION_SECTION_STYLE, NAVIGATION_SUB_SECTION_STYLE } from './Navigationv3';
+import { FileTreeView } from './FileTreeView';
 import type { AsyncAPIDocumentInterface } from '@asyncapi/parser';
 
 interface NavigationProps {
@@ -343,13 +344,16 @@ export const Navigation: React.FunctionComponent<NavigationProps> = ({
 
   if (!rawSpec || !document) {
     return (
-      <div className="flex flex-1 overflow-hidden h-full justify-center items-center text-2xl mx-auto px-6 text-center bg-gray-800">
-        {loading ?(
-          <div className="rotating-wheel"></div>
-        ) : (
-          <p className='text-white'>Empty or invalid document. Please fix errors/define AsyncAPI document.</p>
-        )
-        }
+      <div className={`flex flex-none flex-col overflow-y-auto overflow-x-hidden bg-gray-800 h-full ${className}`}>
+        <FileTreeView />
+        <div className="flex flex-1 overflow-hidden h-full justify-center items-center text-2xl mx-auto px-6 text-center bg-gray-800">
+          {loading ?(
+            <div className="rotating-wheel"></div>
+          ) : (
+            <p className='text-white'>Empty or invalid document. Please fix errors/define AsyncAPI document.</p>
+          )
+          }
+        </div>
       </div>
     );
   }
@@ -357,6 +361,7 @@ export const Navigation: React.FunctionComponent<NavigationProps> = ({
   const components = document.components();
   return (
     <div className={`flex flex-none flex-col overflow-y-auto overflow-x-hidden bg-gray-800 h-full ${className}`}>
+      <FileTreeView />
       <ul>
         <li className="mb-4">
           <div
diff --git a/apps/studio/src/components/Navigationv3.tsx b/apps/studio/src/components/Navigationv3.tsx
index 3efe8143a..40c923465 100644
--- a/apps/studio/src/components/Navigationv3.tsx
+++ b/apps/studio/src/components/Navigationv3.tsx
@@ -4,6 +4,7 @@ import React, { useEffect, useState } from 'react';
 
 import { useServices } from '@/services';
 import { useDocumentsState, useFilesState } from '@/state';
+import { FileTreeView } from './FileTreeView';
 
 import type { AsyncAPIDocumentInterface } from '@asyncapi/parser';
 
@@ -398,8 +399,11 @@ export const Navigationv3: React.FunctionComponent<NavigationProps> = ({
 
   if (!rawSpec || !document) {
     return (
-      <div className="flex overflow-hidden bg-gray-800 h-full justify-center items-center text-center text-white text-md px-6">
-        Empty or invalid document. Please fix errors/define AsyncAPI document.
+      <div className={`flex flex-none flex-col overflow-y-auto overflow-x-hidden bg-gray-800 h-full ${className}`} id="navigation-panel">
+        <FileTreeView />
+        <div className="flex overflow-hidden bg-gray-800 h-full justify-center items-center text-center text-white text-md px-6">
+          Empty or invalid document. Please fix errors/define AsyncAPI document.
+        </div>
       </div>
     );
   }
@@ -407,6 +411,7 @@ export const Navigationv3: React.FunctionComponent<NavigationProps> = ({
   const components = document.components();
   return (
     <div className={`flex flex-none flex-col overflow-y-auto overflow-x-hidden bg-gray-800 h-full ${className}`} id="navigation-panel">
+      <FileTreeView />
       <ul>
         <li className="mb-4">
           <div
diff --git a/apps/studio/src/components/Terminal/ProblemsTab.tsx b/apps/studio/src/components/Terminal/ProblemsTab.tsx
index f54d04015..fccffe6af 100644
--- a/apps/studio/src/components/Terminal/ProblemsTab.tsx
+++ b/apps/studio/src/components/Terminal/ProblemsTab.tsx
@@ -14,8 +14,17 @@ import type { Diagnostic } from '@asyncapi/parser';
 
 interface ProblemsTabProps {}
 
+const emptyDiagnostics = {
+  original: [],
+  filtered: [],
+  errors: [],
+  warnings: [],
+  informations: [],
+  hints: [],
+};
+
 export const ProblemsTab: FunctionComponent<ProblemsTabProps> = () => {
-  const diagnostics = useDocumentsState(state => state.documents['asyncapi'].diagnostics);
+  const diagnostics = useDocumentsState(state => state.documents['asyncapi']?.diagnostics ?? emptyDiagnostics);
 
   const errorDiagnosticsLength = diagnostics.errors.length;
   const warningDiagnosticsLength = diagnostics.warnings.length;
@@ -117,7 +126,7 @@ interface SeverityButtonsProps {
 }
 
 const SeverityButtons: FunctionComponent<SeverityButtonsProps> = ({ active, setActive }) => {
-  const diagnostics = useDocumentsState(state => state.documents['asyncapi'].diagnostics);
+  const diagnostics = useDocumentsState(state => state.documents['asyncapi']?.diagnostics ?? emptyDiagnostics);
   const governanceShowState = useSettingsState(state => state.governance.show);
 
   const errorDiagnostics = diagnostics.errors;
@@ -200,7 +209,7 @@ const SeverityButtons: FunctionComponent<SeverityButtonsProps> = ({ active, setA
 
 export const ProblemsTabContent: FunctionComponent<ProblemsTabProps> = () => {
   const { navigationSvc } = useServices();
-  const diagnostics = useDocumentsState(state => state.documents['asyncapi'].diagnostics);
+  const diagnostics = useDocumentsState(state => state.documents['asyncapi']?.diagnostics ?? emptyDiagnostics);
   const modal = useModal(SettingsModal);
 
   const [active, setActive] = useState<Array<DiagnosticSeverity>>([]);
diff --git a/apps/studio/src/components/Terminal/TerminalInfo.tsx b/apps/studio/src/components/Terminal/TerminalInfo.tsx
index b19c17e98..c399ddb1b 100644
--- a/apps/studio/src/components/Terminal/TerminalInfo.tsx
+++ b/apps/studio/src/components/Terminal/TerminalInfo.tsx
@@ -17,6 +17,10 @@ export const TerminalInfo: FunctionComponent<TerminalInfoProps> = () => {
   const document = useDocumentsState(state => state.documents['asyncapi']);
   const autoSaving = useSettingsState(state => state.editor.autoSaving);
 
+  if (!document) {
+    return null;
+  }
+
   const liveServer = useAppState(state => state.liveServer);
   const actualVersion = document.document?.version() || '2.0.0';
   const latestVersion = specificationSvc.latestVersion;
diff --git a/apps/studio/src/services/app.service.ts b/apps/studio/src/services/app.service.ts
index 386fa3b3d..379cc8eda 100644
--- a/apps/studio/src/services/app.service.ts
+++ b/apps/studio/src/services/app.service.ts
@@ -54,7 +54,6 @@ export class ApplicationService extends AbstractService {
 
     console.log('[DEBUG:app] fetchResource', { url, base64: !!base64, share });
 
-    const { updateFile } = filesState.getState();
     let content = '';
     if (url) {
       content = await fetch(url).then((res) => res.text());
@@ -66,23 +65,39 @@ export class ApplicationService extends AbstractService {
       content = data.content;
     }
 
-    const language = this.svcs.formatSvc.retrieveLangauge(content);
+    const detectedLanguage = this.svcs.formatSvc.retrieveLangauge(content);
+    const language: 'json' | 'yaml' = detectedLanguage === 'json' ? 'json' : 'yaml';
     const source = url || undefined;
-    let from = 'url';
-
-    if (base64) {
-      from = 'base64';
-    } else if (share) {
-      from = 'share';
-    }
-
-    updateFile('asyncapi', {
+    const from = base64 ? 'base64' : share ? 'share' : 'url';
+    const uri = url || (share ? `share://${share}` : 'base64://document');
+    const file = {
+      uri,
+      name: uri.split('/').pop() || uri,
       content,
       language,
       source,
       from: from as 'url' | 'base64' | 'share',
+      modified: false,
       stat: { mtime: Date.now() },
-    });
+      isAsyncApiDocument: /^asyncapi\s*:/m.test(String(content).trim()) || (String(content).trim().startsWith('{') && (() => {
+        try {
+          return !!JSON.parse(String(content)).asyncapi;
+        } catch {
+          return false;
+        }
+      })()),
+    };
+    const projectRoot = url ? (() => {
+      try {
+        return new URL(url).host;
+      } catch {
+        return 'Remote Files';
+      }
+    })() : undefined;
+    filesState.getState().setProjectFiles(
+      { [uri]: file },
+      { activeFileUri: uri, fileTreeMode: url ? 'remote' : 'none', projectRoot },
+    );
   }
 
   private hidePreloader() {
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 3b1e3851c..12e0974c5 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -61,6 +61,145 @@ export class EditorService extends AbstractService {
     return this.editor?.getModel()?.getValue() as string;
   }
 
+  private getFileNameFromUri(uri: string): string {
+    if (!uri) return 'asyncapi';
+    const normalized = uri.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    return parts[parts.length - 1] || uri;
+  }
+
+  private inferLanguageFromUri(uri: string, content?: string): 'json' | 'yaml' {
+    const byContent = content ? this.svcs.formatSvc.retrieveLangauge(content) : undefined;
+    if (byContent === 'json' || byContent === 'yaml') {
+      return byContent;
+    }
+    const lower = uri.toLowerCase();
+    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
+      return 'json';
+    }
+    return 'yaml';
+  }
+
+  private isAsyncApiContent(content: string): boolean {
+    const trimmed = String(content || '').trim();
+    if (!trimmed) return false;
+    if (trimmed.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return !!parsed?.asyncapi;
+      } catch {
+        return false;
+      }
+    }
+    return /^asyncapi\s*:/m.test(trimmed);
+  }
+
+  private hasUnsupportedEditorExtension(uri: string): boolean {
+    const blocked = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2'];
+    const path = uri.split('?')[0].toLowerCase();
+    return blocked.some((ext) => path.endsWith(ext));
+  }
+
+  async switchToFile(uri: string): Promise<void> {
+    const { files, setFileTreeLoading, setActiveFile, updateFile } = filesState.getState();
+    const target = files[String(uri)];
+    if (!target) {
+      return;
+    }
+
+    if (this.hasUnsupportedEditorExtension(uri)) {
+      toast.error('This file type is not supported in the editor.');
+      return;
+    }
+
+    setFileTreeLoading(true);
+    try {
+      let content = target.content;
+      let fileHandle = target.fileHandle;
+      if (!content && fileHandle) {
+        const file = await fileHandle.getFile();
+        content = await file.text();
+      }
+      if (!content && /^https?:\/\//.test(uri)) {
+        content = await fetch(uri).then((res) => res.text());
+      }
+
+      if (typeof content !== 'string') {
+        content = '';
+      }
+
+      const language = this.inferLanguageFromUri(uri, content);
+      updateFile(uri, {
+        content,
+        language,
+        name: target.name || this.getFileNameFromUri(uri),
+        isAsyncApiDocument: this.isAsyncApiContent(content),
+        stat: { mtime: Date.now() },
+      });
+      setActiveFile(uri);
+      this.updateState({
+        content,
+        updateModel: true,
+        sendToServer: false,
+        file: {
+          source: target.source,
+          from: target.from,
+          language,
+          fileHandle,
+          directoryHandle: target.directoryHandle,
+          localPath: target.localPath,
+          name: target.name || this.getFileNameFromUri(uri),
+          isAsyncApiDocument: this.isAsyncApiContent(content),
+          stat: { mtime: Date.now() },
+        },
+      });
+    } finally {
+      setFileTreeLoading(false);
+    }
+  }
+
+  private async collectLocalProjectFiles(
+    directoryHandle: FileSystemDirectoryHandle,
+    basePath = '',
+    rootName = directoryHandle.name,
+  ): Promise<Record<string, File>> {
+    const files: Record<string, File> = {};
+
+    for await (const [, entry] of directoryHandle.entries()) {
+      if (entry.kind === 'directory') {
+        const childPath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        const nested = await this.collectLocalProjectFiles(entry, childPath, rootName);
+        Object.assign(files, nested);
+      } else if (entry.kind === 'file') {
+        const localPath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        const fileHandle = entry as FileSystemFileHandle;
+        try {
+          const file = await fileHandle.getFile();
+          const content = await file.text();
+          const language = this.inferLanguageFromUri(localPath, content);
+          files[localPath] = {
+            uri: localPath,
+            name: this.getFileNameFromUri(localPath),
+            content,
+            from: 'file',
+            source: `${rootName}/${localPath}`,
+            language,
+            modified: false,
+            directoryHandle,
+            fileHandle,
+            localPath,
+            isAsyncApiDocument: this.isAsyncApiContent(content),
+            stat: { mtime: Date.now() },
+          };
+        } catch (err) {
+          console.error('[DEBUG:editor] Failed to read local file for tree', localPath, err);
+        }
+      }
+    }
+
+    return files;
+  }
+
   updateState({
     content,
     updateModel = false,
@@ -103,17 +242,14 @@ export class EditorService extends AbstractService {
   }
 
   async grantFolderAccess(): Promise<void> {
-    // 1. Ask user to pick the root folder
     let directoryHandle: FileSystemDirectoryHandle;
     try {
       directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
     } catch (err: any) {
-      // User cancelled — silently ignore
       if (err?.name === 'AbortError') return;
       throw err;
     }
 
-    // 2. Ask user to pick the AsyncAPI file within that folder
     toast.loading('Please select the AsyncAPI file within the folder...', { id: 'folder-access' });
     let fileHandle: FileSystemFileHandle;
     try {
@@ -128,51 +264,50 @@ export class EditorService extends AbstractService {
       throw err;
     }
 
-    // 3. Compute the relative path of the selected file within the folder
     const pathParts = await directoryHandle.resolve(fileHandle);
     if (!pathParts) {
       toast.dismiss('folder-access');
       toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
       return;
     }
-    const localPath = pathParts.join('/');
 
-    // 4. Read file content
-    const file = await fileHandle.getFile();
-    const content = await file.text();
-    const language = this.svcs.formatSvc.retrieveLangauge(content);
-
-    // 5. Update file state — parser subscription will re-parse automatically with the local resolver
-    console.log(
-      '[DEBUG:editor] grantFolderAccess — updating file state',
-      '\n  from: file',
-      '\n  source:', `${directoryHandle.name}/${localPath}`,
-      '\n  localPath:', localPath,
-      '\n  directoryHandle:', directoryHandle.name,
-    );
-    const { updateFile } = filesState.getState();
-    updateFile('asyncapi', {
-      content,
-      language,
+    const localPath = pathParts.join('/');
+    const files = await this.collectLocalProjectFiles(directoryHandle);
+    const selectedFile = await fileHandle.getFile();
+    const selectedContent = await selectedFile.text();
+    const selectedLanguage = this.inferLanguageFromUri(localPath, selectedContent);
+
+    files[localPath] = {
+      uri: localPath,
+      name: this.getFileNameFromUri(localPath),
+      content: selectedContent,
+      language: selectedLanguage,
       from: 'file',
       source: `${directoryHandle.name}/${localPath}`,
       directoryHandle,
       fileHandle,
       localPath,
       modified: false,
+      isAsyncApiDocument: this.isAsyncApiContent(selectedContent),
       stat: { mtime: Date.now() },
+    };
+
+    filesState.getState().setProjectFiles(files, {
+      activeFileUri: localPath,
+      fileTreeMode: 'local',
+      projectRoot: directoryHandle.name,
     });
 
-    // Update the editor model
-    if (this.editor) {
-      const model = this.editor.getModel();
-      if (model) model.setValue(content);
-    }
+    this.updateState({
+      content: selectedContent,
+      updateModel: true,
+      sendToServer: false,
+      file: files[localPath],
+    });
 
     toast.dismiss('folder-access');
     toast.success('Folder access granted! File references will now be resolved.');
   }
-
   async importFromURL(url: string): Promise<void> {
     if (!url) {
       throw new Error('URL is required');
@@ -180,24 +315,43 @@ export class EditorService extends AbstractService {
 
     console.log('[DEBUG:editor] importFromURL', url);
 
-    // Update browser URL with ?url= parameter (no page reload)
     const currentUrl = window.location.href.split('?')[0];
     window.history.pushState({}, '', `${currentUrl}?url=${url}`);
 
     return fetch(url)
       .then(res => res.text())
       .then(async text => {
-        const language = this.svcs.formatSvc.retrieveLangauge(text);
+        const language = this.inferLanguageFromUri(url, text);
+        const projectRoot = (() => {
+          try {
+            return new URL(url).host;
+          } catch {
+            return 'Remote Files';
+          }
+        })();
+
+        const mainFile: File = {
+          uri: url,
+          name: this.getFileNameFromUri(url),
+          content: text,
+          from: 'url',
+          source: url,
+          language,
+          modified: false,
+          isAsyncApiDocument: this.isAsyncApiContent(text),
+          stat: { mtime: Date.now() },
+        };
+
+        filesState.getState().setProjectFiles(
+          { [url]: mainFile },
+          { activeFileUri: url, fileTreeMode: 'remote', projectRoot },
+        );
 
         this.updateState({
           content: text,
           updateModel: true,
-          file: {
-            source: url,
-            from: 'url',
-            language,
-            stat: { mtime: Date.now() },
-          },
+          sendToServer: false,
+          file: mainFile,
         });
       })
       .catch(err => {
@@ -205,7 +359,6 @@ export class EditorService extends AbstractService {
         throw err;
       });
   }
-
   async importFile(files: FileList | null) {
     if (files === null || files?.length !== 1) {
       return;
@@ -215,7 +368,6 @@ export class EditorService extends AbstractService {
       return;
     }
 
-    // Validate by extension — MIME types are unreliable across browsers
     const allowedExtensions = ['json', 'yaml', 'yml', 'avsc'];
     const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
     if (!allowedExtensions.includes(ext)) {
@@ -226,40 +378,68 @@ export class EditorService extends AbstractService {
 
     const fileReader = new FileReader();
     fileReader.onload = fileLoadedEvent => {
-      const content = fileLoadedEvent.target?.result;
+      const content = String(fileLoadedEvent.target?.result || '');
+      const uri = file.name;
+      const language = this.inferLanguageFromUri(uri, content);
+      const importedFile: File = {
+        uri,
+        name: file.name,
+        content,
+        from: 'file',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(content),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
       this.updateState({
-        content: String(content),
+        content,
         updateModel: true,
-        file: {
-          from: 'file',
-          source: undefined,
-          directoryHandle: undefined,
-          fileHandle: undefined,
-          localPath: undefined,
-          stat: { mtime: Date.now() },
-        },
+        sendToServer: false,
+        file: importedFile,
       });
     };
     fileReader.readAsText(file, 'UTF-8');
   }
-
   async importBase64(content: string) {
     try {
       const decoded = this.svcs.formatSvc.decodeBase64(content);
-      this.updateState({ 
-        content: String(decoded), 
-        updateModel: true, 
-        file: { 
-          from: 'base64', 
-          source: undefined, 
-        },
+      const uri = 'base64://document';
+      const language = this.inferLanguageFromUri(uri, String(decoded));
+      const importedFile: File = {
+        uri,
+        name: 'Base64 document',
+        content: String(decoded),
+        from: 'base64',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(String(decoded)),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
+      this.updateState({
+        content: String(decoded),
+        updateModel: true,
+        sendToServer: false,
+        file: importedFile,
       });
     } catch (err) {
       console.error(err);
       throw err;
     }
   }
-
   async importFromShareID(shareID: string) {
     try {
       const response = await fetch(`/share/${shareID}`);
@@ -268,20 +448,36 @@ export class EditorService extends AbstractService {
       }
 
       const data = await response.json();
-      this.updateState({ 
-        content: data.content, 
-        updateModel: true, 
-        file: { 
-          from: 'share', 
-          source: undefined, 
-        },
+      const uri = `share://${shareID}`;
+      const language = this.inferLanguageFromUri(uri, data.content);
+      const importedFile: File = {
+        uri,
+        name: `Shared ${shareID}`,
+        content: data.content,
+        from: 'share',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(data.content),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
+      this.updateState({
+        content: data.content,
+        updateModel: true,
+        sendToServer: false,
+        file: importedFile,
       });
     } catch (err) {
       console.error(err);
       throw err;
     }
   }
-
   async exportAsURL() {
     try {
       const file = filesState.getState().files['asyncapi'];
@@ -538,3 +734,5 @@ export class EditorService extends AbstractService {
     });
   }
 }
+
+
diff --git a/apps/studio/src/services/local-file-resolver.ts b/apps/studio/src/services/local-file-resolver.ts
index 7586edffc..342907eb9 100644
--- a/apps/studio/src/services/local-file-resolver.ts
+++ b/apps/studio/src/services/local-file-resolver.ts
@@ -79,6 +79,12 @@ export interface LocalFileResolverOptions {
   directoryHandle: FileSystemDirectoryHandle;
   /** Relative path of the main AsyncAPI file within the folder, e.g. "asyncapi.yaml" or "specs/api.yaml" */
   basePath: string;
+  onReadFile?: (file: {
+    relativePath: string;
+    source: string;
+    content: string;
+    fileHandle: FileSystemFileHandle;
+  }) => Promise<void> | void;
 }
 
 /**
@@ -101,7 +107,7 @@ function extractPath(uri: any): string {
  * (which would fail in the browser with "readFile is not a function").
  */
 export function createLocalFileResolver(options: LocalFileResolverOptions) {
-  const { directoryHandle, basePath } = options;
+  const { directoryHandle, basePath, onReadFile } = options;
   // The source passed to the parser is `folderName/localPath` (e.g. "apis/asyncapi.yml").
   // The parser resolves $refs relative to that source, producing paths like
   // "apis/schemas/User.avsc".  We need to strip the folder name prefix to get
@@ -135,9 +141,16 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
       const fileHandle = await getFileHandleFromPath(directoryHandle, relativePath);
       const file = await fileHandle.getFile();
       const content = await file.text();
+      if (onReadFile) {
+        await onReadFile({
+          relativePath,
+          source: `${directoryHandle.name}/${relativePath}`,
+          content,
+          fileHandle,
+        });
+      }
       console.log('[DEBUG:resolver] read() success for', relativePath, `(${content.length} chars)`);
       return content;
     },
   };
 }
-
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index 37f7e9ff2..070db6e43 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -51,9 +51,21 @@ export class ParserService extends AbstractService {
       options.source = uri;
     }
 
+    const active = filesState.getState().files['asyncapi'];
+    if (uri !== 'asyncapi') {
+      return;
+    }
+
+    if (!this.isAsyncApiDocument(spec)) {
+      filesState.getState().updateFile('asyncapi', { isAsyncApiDocument: false });
+      return;
+    }
+    filesState.getState().updateFile('asyncapi', { isAsyncApiDocument: true });
+
     // Inject local file resolver when the file was opened from local disk with folder access
-    const file = filesState.getState().files[String(uri)];
+    const file = active;
     const useLocalResolver = !!(file?.from === 'file' && file.directoryHandle && file.localPath);
+    const useRemoteResolver = !!(file?.from === 'url' && /^https?:\/\//.test(file.source || ''));
     console.log(
       '[DEBUG:parser] parse()', uri,
       '\n  file.from:', file?.from,
@@ -63,14 +75,38 @@ export class ParserService extends AbstractService {
       '\n  options.source:', options.source,
       '\n  → resolver:', useLocalResolver ? 'LOCAL FILE RESOLVER' : 'default (remote/HTTP)',
     );
+    const resolvers: any[] = [];
     if (useLocalResolver && file.directoryHandle && file.localPath) {
       const resolver = createLocalFileResolver({
         directoryHandle: file.directoryHandle,
         basePath: file.localPath,
+        onReadFile: async ({ relativePath, source, content, fileHandle }) => {
+          filesState.getState().updateFile(relativePath, {
+            uri: relativePath,
+            name: relativePath.split('/').pop() || relativePath,
+            content,
+            from: 'file',
+            source,
+            language: this.inferLanguage(relativePath, content),
+            modified: false,
+            directoryHandle: file.directoryHandle,
+            fileHandle,
+            localPath: relativePath,
+            stat: { mtime: Date.now() },
+            isAsyncApiDocument: this.isAsyncApiDocument(content),
+          });
+        },
       });
+      resolvers.push(resolver);
+    }
+    if (useRemoteResolver) {
+      resolvers.push(this.createRemoteTrackingResolver('http'));
+      resolvers.push(this.createRemoteTrackingResolver('https'));
+    }
+    if (resolvers.length > 0) {
       (options as any).__unstable = {
         resolver: {
-          resolvers: [resolver],
+          resolvers,
         },
       };
     }
@@ -156,6 +192,57 @@ export class ParserService extends AbstractService {
 
   private updateDocument = documentsState.getState().updateDocument;
 
+  private inferLanguage(uri: string, content: string): 'json' | 'yaml' {
+    if (uri.toLowerCase().endsWith('.json') || uri.toLowerCase().endsWith('.avsc')) {
+      return 'json';
+    }
+    const trimmed = String(content || '').trim();
+    return trimmed.startsWith('{') ? 'json' : 'yaml';
+  }
+
+  private isAsyncApiDocument(spec: string): boolean {
+    const trimmed = String(spec || '').trim();
+    if (!trimmed) return false;
+    if (trimmed.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return !!parsed?.asyncapi;
+      } catch {
+        return false;
+      }
+    }
+    return /^asyncapi\s*:/m.test(trimmed);
+  }
+
+  private createRemoteTrackingResolver(schema: 'http' | 'https') {
+    const isAsyncApiDocument = this.isAsyncApiDocument.bind(this);
+    const inferLanguage = this.inferLanguage.bind(this);
+    return {
+      schema,
+      order: 1,
+      canRead(uri: any) {
+        const url = String(uri);
+        return /^https?:\/\//.test(url);
+      },
+      async read(uri: any): Promise<string> {
+        const url = String(uri);
+        const content = await fetch(url).then((res) => res.text());
+        filesState.getState().updateFile(url, {
+          uri: url,
+          name: url.split('/').pop() || url,
+          content,
+          from: 'url',
+          source: url,
+          language: inferLanguage(url, content),
+          modified: false,
+          stat: { mtime: Date.now() },
+          isAsyncApiDocument: isAsyncApiDocument(content),
+        });
+        return content;
+      },
+    };
+  }
+
   private createDiagnostics(diagnostics: Diagnostic[]) {
     // Map unresolvable local file ref errors to a clear, actionable message
     diagnostics.forEach(diagnostic => {
@@ -207,30 +294,24 @@ export class ParserService extends AbstractService {
     }
 
     this.unsubscribeFiles = filesState.subscribe((state, prevState) => {
-      const newFiles = state.files;
-      const oldFiles = prevState.files;
-
-      Object.entries(newFiles).forEach(([uri, file]) => {
-        const oldFile = oldFiles[String(uri)];
-        if (file === oldFile) return;
-
-        // Skip cosmetic-only changes (from, modified, language, name).
-        // Re-parse only when content, resolver configuration, or the explicit
-        // freshness timestamp (stat.mtime) changed.
-        const contentChanged = file.content !== oldFile?.content;
-        const sourceChanged = file.source !== oldFile?.source;
-        const directoryHandleChanged = file.directoryHandle !== oldFile?.directoryHandle;
-        const localPathChanged = file.localPath !== oldFile?.localPath;
-        const mtimeChanged = file.stat?.mtime !== oldFile?.stat?.mtime;
-
-        console.log('[DEBUG:parser] subscribeToFiles', uri, { contentChanged, sourceChanged, directoryHandleChanged, localPathChanged, mtimeChanged });
-
-        if (!contentChanged && !sourceChanged && !directoryHandleChanged && !localPathChanged && !mtimeChanged) {
-          return;
-        }
+      const file = state.files['asyncapi'];
+      const oldFile = prevState.files['asyncapi'];
+      if (!file || file === oldFile) return;
 
-        this.parse(uri, file.content, { source: file.source }).catch(console.error);
-      });
+      const activeChanged = state.activeFileUri !== prevState.activeFileUri;
+      const contentChanged = file.content !== oldFile?.content;
+      const sourceChanged = file.source !== oldFile?.source;
+      const directoryHandleChanged = file.directoryHandle !== oldFile?.directoryHandle;
+      const localPathChanged = file.localPath !== oldFile?.localPath;
+      const mtimeChanged = file.stat?.mtime !== oldFile?.stat?.mtime;
+
+      console.log('[DEBUG:parser] subscribeToFiles', 'asyncapi', { activeChanged, contentChanged, sourceChanged, directoryHandleChanged, localPathChanged, mtimeChanged });
+
+      if (!activeChanged && !contentChanged && !sourceChanged && !directoryHandleChanged && !localPathChanged && !mtimeChanged) {
+        return;
+      }
+
+      this.parse('asyncapi', file.content, { source: file.source }).catch(console.error);
     });
   }
 
@@ -244,19 +325,18 @@ export class ParserService extends AbstractService {
     this.unsubscribeSettings = settingsState.subscribe((state, prevState) => {
       if (isDeepEqual(state.governance, prevState.governance)) return;
 
-      const { files } = filesState.getState();
-      Object.entries(files).forEach(([uri, file]) => {
-        this.parse(uri, file.content).catch(console.error);
-      });
+      const file = filesState.getState().files['asyncapi'];
+      if (file) {
+        this.parse('asyncapi', file.content, { source: file.source }).catch(console.error);
+      }
     });
   }
 
   private parseSavedDocuments() {
-    const { files } = filesState.getState();
-    return Promise.all(
-      Object.entries(files).map(([uri, file]) => {
-        return this.parse(uri, file.content);
-      }),
-    );
+    const file = filesState.getState().files['asyncapi'];
+    if (!file) {
+      return Promise.resolve([]);
+    }
+    return Promise.all([this.parse('asyncapi', file.content, { source: file.source })]);
   }
 }
diff --git a/apps/studio/src/state/documents.state.ts b/apps/studio/src/state/documents.state.ts
index 3dc90ca70..057a84a7c 100644
--- a/apps/studio/src/state/documents.state.ts
+++ b/apps/studio/src/state/documents.state.ts
@@ -27,10 +27,38 @@ export type DocumentsActions = {
   updateDocument: (uri: string, document: Partial<Document>) => void;
 }
 
+const emptyDiagnostics: DocumentDiagnostics = {
+  original: [],
+  filtered: [],
+  errors: [],
+  warnings: [],
+  informations: [],
+  hints: [],
+};
+
 export const documentsState = create<DocumentsState & DocumentsActions>(set => ({
-  documents: {},
+  documents: {
+    asyncapi: {
+      uri: 'asyncapi',
+      document: undefined,
+      extras: undefined,
+      diagnostics: emptyDiagnostics,
+      valid: false,
+    },
+  },
   updateDocument(uri: string, document: Partial<Document>) {
-    set(state => ({ documents: { ...state.documents, [String(uri)]: { ...state.documents[String(uri)] || {}, ...document } } }));
+    set(state => ({
+      documents: {
+        ...state.documents,
+        [String(uri)]: {
+          uri: String(uri),
+          diagnostics: emptyDiagnostics,
+          valid: false,
+          ...state.documents[String(uri)] || {},
+          ...document,
+        }
+      }
+    }));
   },
 }));
 
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index 431945ce4..9933f2c02 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -248,20 +248,34 @@ export type File = {
   language: 'json' | 'yaml';
   modified: boolean;
   stat?: FileStat;
-  /** File System Access API handle for the specific file (Stage 4: save-back) */
   fileHandle?: FileSystemFileHandle;
-  /** File System Access API handle for the containing folder (Stage 2/3: local $ref resolution) */
   directoryHandle?: FileSystemDirectoryHandle;
-  /** Relative path of this file within the directoryHandle folder, e.g. "asyncapi.yaml" or "specs/api.yaml" */
   localPath?: string;
+  isAsyncApiDocument?: boolean;
 }
 
+export type FileTreeMode = 'none' | 'local' | 'remote';
+
 export type FilesState = {
   files: Record<string, File>;
+  activeFileUri: string;
+  fileTreeMode: FileTreeMode;
+  projectRoot?: string;
+  fileTreeLoading: boolean;
 }
 
 export type FilesActions = {
   updateFile: (uri: string, file: Partial<File>) => void;
+  setActiveFile: (uri: string) => void;
+  setProjectFiles: (
+    files: Record<string, File>,
+    options?: {
+      activeFileUri?: string;
+      fileTreeMode?: FileTreeMode;
+      projectRoot?: string;
+    },
+  ) => void;
+  setFileTreeLoading: (loading: boolean) => void;
 }
 
 export const filesState = create<FilesState & FilesActions>((set, get) => ({
@@ -271,7 +285,7 @@ export const filesState = create<FilesState & FilesActions>((set, get) => ({
       name: 'asyncapi',
       content: schema,
       from: 'storage',
-      source: documentSource, // Use source from localStorage if available
+      source: documentSource,
       language: schema.trimStart()[0] === '{' ? 'json' : 'yaml',
       modified: false,
       stat: {
@@ -279,18 +293,73 @@ export const filesState = create<FilesState & FilesActions>((set, get) => ({
       }
     }
   },
+  activeFileUri: 'asyncapi',
+  fileTreeMode: 'none',
+  projectRoot: undefined,
+  fileTreeLoading: false,
   updateFile(uri: string, file: Partial<File>) {
     const before = get().files[String(uri)];
     const logBefore = before
       ? { from: before.from, source: before.source, localPath: before.localPath, hasDirectoryHandle: !!before.directoryHandle, hasFileHandle: !!before.fileHandle }
       : '(new file)';
     const logPatch = { from: file.from, source: file.source, localPath: file.localPath, hasDirectoryHandle: !!file.directoryHandle, hasFileHandle: !!file.fileHandle };
-    console.log('[DEBUG:filesState] updateFile ▶', uri, '\n  before:', logBefore, '\n  patch: ', logPatch);
-    set(state => ({ files: { ...state.files, [String(uri)]: { ...state.files[String(uri)] || {}, ...file } } }));
+    console.log('[DEBUG:filesState] updateFile', uri, '\n  before:', logBefore, '\n  patch: ', logPatch);
+    set((state) => {
+      const nextFiles: Record<string, File> = {
+        ...state.files,
+        [String(uri)]: { ...state.files[String(uri)] || {}, ...file } as File,
+      };
+      if (String(uri) === 'asyncapi' && state.activeFileUri !== 'asyncapi' && nextFiles[state.activeFileUri]) {
+        nextFiles[state.activeFileUri] = { ...nextFiles[state.activeFileUri], ...file, uri: state.activeFileUri };
+      }
+      if (String(uri) === state.activeFileUri && String(uri) !== 'asyncapi' && nextFiles.asyncapi) {
+        nextFiles.asyncapi = { ...nextFiles.asyncapi, ...file, uri: state.activeFileUri };
+      }
+      return { files: nextFiles };
+    });
     const after = get().files[String(uri)];
     const logAfter = { from: after.from, source: after.source, localPath: after.localPath, hasDirectoryHandle: !!after.directoryHandle, hasFileHandle: !!after.fileHandle };
-    console.log('[DEBUG:filesState] updateFile ◀', uri, '\n  after: ', logAfter);
-  }
+    console.log('[DEBUG:filesState] updateFile', uri, '\n  after: ', logAfter);
+  },
+  setActiveFile(uri: string) {
+    const selected = get().files[String(uri)];
+    if (!selected) {
+      return;
+    }
+    set((state) => ({
+      activeFileUri: uri,
+      files: {
+        ...state.files,
+        asyncapi: {
+          ...state.files.asyncapi,
+          ...selected,
+          uri,
+        },
+      },
+    }));
+  },
+  setProjectFiles(nextProjectFiles, options = {}) {
+    const candidateActiveUri = options.activeFileUri || Object.keys(nextProjectFiles)[0] || 'asyncapi';
+    const selected = nextProjectFiles[candidateActiveUri];
+    const activeFileUri = selected ? candidateActiveUri : 'asyncapi';
+
+    set((state) => ({
+      files: {
+        asyncapi: selected
+          ? { ...state.files.asyncapi, ...selected, uri: activeFileUri }
+          : state.files.asyncapi,
+        ...nextProjectFiles,
+      },
+      activeFileUri,
+      fileTreeMode: options.fileTreeMode ?? state.fileTreeMode,
+      projectRoot: options.projectRoot ?? state.projectRoot,
+      fileTreeLoading: false,
+    }));
+  },
+  setFileTreeLoading(loading: boolean) {
+    set({ fileTreeLoading: loading });
+  },
 }));
 
 export const useFilesState = filesState;
+

From eb22384391139b984b8902c6b283ac006c031963 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Tue, 3 Mar 2026 19:25:50 +0100
Subject: [PATCH 07/23] tree view

---
 apps/studio/src/components/FileTreeView.tsx | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/apps/studio/src/components/FileTreeView.tsx b/apps/studio/src/components/FileTreeView.tsx
index c4769355b..87fffd41b 100644
--- a/apps/studio/src/components/FileTreeView.tsx
+++ b/apps/studio/src/components/FileTreeView.tsx
@@ -89,7 +89,17 @@ function truncateExternalUrl(url: string): string {
 }
 
 function formatRemoteGroupLabel(url: string): string {
-  return url;
+  try {
+    const parsed = new URL(url);
+    const host = parsed.host;
+    const port = parsed.port;
+    const fullhost = port ? `${host}:${port}` : host;
+    const parts = parsed.pathname.split('/').filter(Boolean);
+    const tail = parts.length > 0 ? parts[parts.length - 1] : parsed.host;
+    return `${parsed.protocol}//${fullhost}/.../${tail}/`;
+  } catch {
+    return truncateExternalUrl(url);
+  }
 }
 
 export const FileTreeView: React.FC = () => {

From 53bac5c0da5485c3fdeb58d98ca22d94a53c9aad Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 11:17:07 +0100
Subject: [PATCH 08/23] fix: linting errors

---
 .../src/components/Editor/ConvertDropdown.tsx |  1 -
 apps/studio/src/components/FileTreeView.tsx   |  2 +-
 .../src/helpers/file-system-access.types.ts   |  2 ++
 apps/studio/src/services/app.service.ts       | 11 +++++---
 apps/studio/src/services/editor.service.tsx   | 25 ++++++++++---------
 .../src/services/local-file-resolver.ts       | 12 +++++----
 apps/studio/src/services/parser.service.ts    |  6 ++---
 apps/studio/src/state/files.state.ts          |  5 ++--
 8 files changed, 37 insertions(+), 27 deletions(-)
 create mode 100644 apps/studio/src/helpers/file-system-access.types.ts

diff --git a/apps/studio/src/components/Editor/ConvertDropdown.tsx b/apps/studio/src/components/Editor/ConvertDropdown.tsx
index b5480b576..8e414a255 100644
--- a/apps/studio/src/components/Editor/ConvertDropdown.tsx
+++ b/apps/studio/src/components/Editor/ConvertDropdown.tsx
@@ -78,4 +78,3 @@ export const ConvertDropdown: React.FC = () => {
   );
 }
 
-
diff --git a/apps/studio/src/components/FileTreeView.tsx b/apps/studio/src/components/FileTreeView.tsx
index 87fffd41b..9fa5fff49 100644
--- a/apps/studio/src/components/FileTreeView.tsx
+++ b/apps/studio/src/components/FileTreeView.tsx
@@ -135,7 +135,7 @@ export const FileTreeView: React.FC = () => {
   );
 
   const remoteTree = useMemo(() => {
-    const remoteFiles = projectFiles.filter((file) => /^https?:\/\//.test(file.uri));
+    const remoteFiles = projectFiles.filter((file) => (/^https?:\/\//).test(file.uri));
     const mainRemote = remoteFiles.find((file) => file.isAsyncApiDocument) || remoteFiles[0];
     const baseDir = (() => {
       if (!mainRemote) return undefined;
diff --git a/apps/studio/src/helpers/file-system-access.types.ts b/apps/studio/src/helpers/file-system-access.types.ts
new file mode 100644
index 000000000..73282b001
--- /dev/null
+++ b/apps/studio/src/helpers/file-system-access.types.ts
@@ -0,0 +1,2 @@
+export type DirectoryHandle = Awaited<ReturnType<Window['showDirectoryPicker']>>;
+export type FileHandle = Awaited<ReturnType<Window['showOpenFilePicker']>>[number];
diff --git a/apps/studio/src/services/app.service.ts b/apps/studio/src/services/app.service.ts
index 379cc8eda..338bf956b 100644
--- a/apps/studio/src/services/app.service.ts
+++ b/apps/studio/src/services/app.service.ts
@@ -68,7 +68,12 @@ export class ApplicationService extends AbstractService {
     const detectedLanguage = this.svcs.formatSvc.retrieveLangauge(content);
     const language: 'json' | 'yaml' = detectedLanguage === 'json' ? 'json' : 'yaml';
     const source = url || undefined;
-    const from = base64 ? 'base64' : share ? 'share' : 'url';
+    let from: 'url' | 'base64' | 'share' = 'url';
+    if (base64) {
+      from = 'base64';
+    } else if (share) {
+      from = 'share';
+    }
     const uri = url || (share ? `share://${share}` : 'base64://document');
     const file = {
       uri,
@@ -76,10 +81,10 @@ export class ApplicationService extends AbstractService {
       content,
       language,
       source,
-      from: from as 'url' | 'base64' | 'share',
+      from,
       modified: false,
       stat: { mtime: Date.now() },
-      isAsyncApiDocument: /^asyncapi\s*:/m.test(String(content).trim()) || (String(content).trim().startsWith('{') && (() => {
+      isAsyncApiDocument: (/^asyncapi\s*:/m).test(String(content).trim()) || (String(content).trim().startsWith('{') && (() => {
         try {
           return !!JSON.parse(String(content)).asyncapi;
         } catch {
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 12e0974c5..77957406e 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -7,6 +7,7 @@ import toast from 'react-hot-toast';
 import fileDownload from 'js-file-download';
 
 import { appState, documentsState, filesState, settingsState } from '@/state';
+import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
 
 import type * as monacoAPI from 'monaco-editor/esm/vs/editor/editor.api';
 import type { Diagnostic } from '@asyncapi/parser';
@@ -91,7 +92,7 @@ export class EditorService extends AbstractService {
         return false;
       }
     }
-    return /^asyncapi\s*:/m.test(trimmed);
+    return (/^asyncapi\s*:/m).test(trimmed);
   }
 
   private hasUnsupportedEditorExtension(uri: string): boolean {
@@ -115,12 +116,12 @@ export class EditorService extends AbstractService {
     setFileTreeLoading(true);
     try {
       let content = target.content;
-      let fileHandle = target.fileHandle;
+      const fileHandle = target.fileHandle;
       if (!content && fileHandle) {
         const file = await fileHandle.getFile();
         content = await file.text();
       }
-      if (!content && /^https?:\/\//.test(uri)) {
+      if (!content && (/^https?:\/\//).test(uri)) {
         content = await fetch(uri).then((res) => res.text());
       }
 
@@ -159,7 +160,7 @@ export class EditorService extends AbstractService {
   }
 
   private async collectLocalProjectFiles(
-    directoryHandle: FileSystemDirectoryHandle,
+    directoryHandle: DirectoryHandle,
     basePath = '',
     rootName = directoryHandle.name,
   ): Promise<Record<string, File>> {
@@ -172,7 +173,7 @@ export class EditorService extends AbstractService {
         Object.assign(files, nested);
       } else if (entry.kind === 'file') {
         const localPath = basePath ? `${basePath}/${entry.name}` : entry.name;
-        const fileHandle = entry as FileSystemFileHandle;
+        const fileHandle = entry as FileHandle;
         try {
           const file = await fileHandle.getFile();
           const content = await file.text();
@@ -242,7 +243,8 @@ export class EditorService extends AbstractService {
   }
 
   async grantFolderAccess(): Promise<void> {
-    let directoryHandle: FileSystemDirectoryHandle;
+    const folderAccessToastId = 'folder-access';
+    let directoryHandle: DirectoryHandle;
     try {
       directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
     } catch (err: any) {
@@ -250,8 +252,8 @@ export class EditorService extends AbstractService {
       throw err;
     }
 
-    toast.loading('Please select the AsyncAPI file within the folder...', { id: 'folder-access' });
-    let fileHandle: FileSystemFileHandle;
+    toast.loading('Please select the AsyncAPI file within the folder...', { id: folderAccessToastId });
+    let fileHandle: FileHandle;
     try {
       const [handle] = await window.showOpenFilePicker({
         types: [{ description: 'AsyncAPI files', accept: { 'text/*': ['.yaml', '.yml', '.json'] } }],
@@ -259,14 +261,14 @@ export class EditorService extends AbstractService {
       });
       fileHandle = handle;
     } catch (err: any) {
-      toast.dismiss('folder-access');
+      toast.dismiss(folderAccessToastId);
       if (err?.name === 'AbortError') return;
       throw err;
     }
 
     const pathParts = await directoryHandle.resolve(fileHandle);
     if (!pathParts) {
-      toast.dismiss('folder-access');
+      toast.dismiss(folderAccessToastId);
       toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
       return;
     }
@@ -305,7 +307,7 @@ export class EditorService extends AbstractService {
       file: files[localPath],
     });
 
-    toast.dismiss('folder-access');
+    toast.dismiss(folderAccessToastId);
     toast.success('Folder access granted! File references will now be resolved.');
   }
   async importFromURL(url: string): Promise<void> {
@@ -735,4 +737,3 @@ export class EditorService extends AbstractService {
   }
 }
 
-
diff --git a/apps/studio/src/services/local-file-resolver.ts b/apps/studio/src/services/local-file-resolver.ts
index 342907eb9..1d644b5fe 100644
--- a/apps/studio/src/services/local-file-resolver.ts
+++ b/apps/studio/src/services/local-file-resolver.ts
@@ -1,3 +1,5 @@
+import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
+
 /**
  * Local File Resolver for AsyncAPI Parser (Stage 2/3)
  *
@@ -40,9 +42,9 @@ export function normaliseRelativePath(basePath: string, relativePath: string): s
  * Throws descriptive errors if intermediate directories or the final file are not found.
  */
 export async function getFileHandleFromPath(
-  directoryHandle: FileSystemDirectoryHandle,
+  directoryHandle: DirectoryHandle,
   filePath: string,
-): Promise<FileSystemFileHandle> {
+): Promise<FileHandle> {
   const parts = filePath.split('/').filter(Boolean);
   const fileName = parts.pop();
 
@@ -76,14 +78,14 @@ export async function getFileHandleFromPath(
 }
 
 export interface LocalFileResolverOptions {
-  directoryHandle: FileSystemDirectoryHandle;
+  directoryHandle: DirectoryHandle;
   /** Relative path of the main AsyncAPI file within the folder, e.g. "asyncapi.yaml" or "specs/api.yaml" */
   basePath: string;
   onReadFile?: (file: {
     relativePath: string;
     source: string;
     content: string;
-    fileHandle: FileSystemFileHandle;
+    fileHandle: FileHandle;
   }) => Promise<void> | void;
 }
 
@@ -112,7 +114,7 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
   // The parser resolves $refs relative to that source, producing paths like
   // "apis/schemas/User.avsc".  We need to strip the folder name prefix to get
   // the path relative to the directoryHandle (e.g. "schemas/User.avsc").
-  const folderPrefix = directoryHandle.name + '/';
+  const folderPrefix = `${directoryHandle.name  }/`;
 
   console.log('[DEBUG:resolver] createLocalFileResolver created', { basePath, folderName: directoryHandle.name, folderPrefix });
 
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index 070db6e43..20e84dd36 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -65,7 +65,7 @@ export class ParserService extends AbstractService {
     // Inject local file resolver when the file was opened from local disk with folder access
     const file = active;
     const useLocalResolver = !!(file?.from === 'file' && file.directoryHandle && file.localPath);
-    const useRemoteResolver = !!(file?.from === 'url' && /^https?:\/\//.test(file.source || ''));
+    const useRemoteResolver = !!(file?.from === 'url' && (/^https?:\/\//).test(file.source || ''));
     console.log(
       '[DEBUG:parser] parse()', uri,
       '\n  file.from:', file?.from,
@@ -211,7 +211,7 @@ export class ParserService extends AbstractService {
         return false;
       }
     }
-    return /^asyncapi\s*:/m.test(trimmed);
+    return (/^asyncapi\s*:/m).test(trimmed);
   }
 
   private createRemoteTrackingResolver(schema: 'http' | 'https') {
@@ -222,7 +222,7 @@ export class ParserService extends AbstractService {
       order: 1,
       canRead(uri: any) {
         const url = String(uri);
-        return /^https?:\/\//.test(url);
+        return (/^https?:\/\//).test(url);
       },
       async read(uri: any): Promise<string> {
         const url = String(uri);
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index 9933f2c02..47e1c32d0 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -1,4 +1,5 @@
 import { create } from 'zustand';
+import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
 
 // Helper function to extract content and source from localStorage
 const getDocumentFromLocalStorage = () => {
@@ -248,8 +249,8 @@ export type File = {
   language: 'json' | 'yaml';
   modified: boolean;
   stat?: FileStat;
-  fileHandle?: FileSystemFileHandle;
-  directoryHandle?: FileSystemDirectoryHandle;
+  fileHandle?: FileHandle;
+  directoryHandle?: DirectoryHandle;
   localPath?: string;
   isAsyncApiDocument?: boolean;
 }

From ee295ab9fcf283b3dfdbe42c2413bd791cc03e22 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 11:29:06 +0100
Subject: [PATCH 09/23] (keep an eye) authomatic fixes for Sonnar warnings

---
 apps/studio/src/components/Editor/MonacoWrapper.tsx |  9 +++++----
 .../studio/src/components/Terminal/TerminalInfo.tsx | 13 ++++++-------
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index 46010d60c..e264bc630 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -14,9 +14,6 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
   const { editorSvc } = useServices();
   const { autoSaving, savingDelay } = useSettingsState(state => state.editor);
   const file = useFilesState(state => state.files['asyncapi']);
-  if (!file) {
-    return null;
-  }
 
   const onChange = useMemo(() => {
     return debounce((v: string) => {
@@ -26,7 +23,11 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
       autoSaving && editorSvc.saveToLocalStorage(v, false);
       // subscribeToFiles will trigger a re-parse when content changes
     }, savingDelay);
-  }, [autoSaving, savingDelay, file?.source]);
+  }, [autoSaving, savingDelay, file?.source, editorSvc]);
+
+  if (!file) {
+    return null;
+  }
 
   return (
     <MonacoEditor
diff --git a/apps/studio/src/components/Terminal/TerminalInfo.tsx b/apps/studio/src/components/Terminal/TerminalInfo.tsx
index c399ddb1b..e62064626 100644
--- a/apps/studio/src/components/Terminal/TerminalInfo.tsx
+++ b/apps/studio/src/components/Terminal/TerminalInfo.tsx
@@ -16,20 +16,19 @@ export const TerminalInfo: FunctionComponent<TerminalInfoProps> = () => {
   const file = useFilesState(state => state.files['asyncapi']);
   const document = useDocumentsState(state => state.documents['asyncapi']);
   const autoSaving = useSettingsState(state => state.editor.autoSaving);
-
-  if (!document) {
-    return null;
-  }
-
   const liveServer = useAppState(state => state.liveServer);
-  const actualVersion = document.document?.version() || '2.0.0';
-  const latestVersion = specificationSvc.latestVersion;
 
   const onNonLatestClick = useCallback((e: {stopPropagation: ()=>void}) => {
     e.stopPropagation();
     show(ConvertToLatestModal);
   }, []);
 
+  if (!document) {
+    return null;
+  }
+  const actualVersion = document.document?.version() || '2.0.0';
+  const latestVersion = specificationSvc.latestVersion;
+
   return (
     <div className="flex flex-row px-2">
       {liveServer && (

From ca01b8c0676cbc5a721c62b84cb7a83c714577a2 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 11:43:04 +0100
Subject: [PATCH 10/23] fix for netlify build error

---
 .../src/helpers/file-system-access.types.ts      | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/apps/studio/src/helpers/file-system-access.types.ts b/apps/studio/src/helpers/file-system-access.types.ts
index 73282b001..1774b9847 100644
--- a/apps/studio/src/helpers/file-system-access.types.ts
+++ b/apps/studio/src/helpers/file-system-access.types.ts
@@ -1,2 +1,14 @@
-export type DirectoryHandle = Awaited<ReturnType<Window['showDirectoryPicker']>>;
-export type FileHandle = Awaited<ReturnType<Window['showOpenFilePicker']>>[number];
+export interface FileHandle {
+  kind: 'file';
+  name: string;
+  getFile: () => Promise<File>;
+}
+
+export interface DirectoryHandle {
+  kind: 'directory';
+  name: string;
+  entries: () => AsyncIterableIterator<[string, DirectoryHandle | FileHandle]>;
+  getDirectoryHandle: (name: string) => Promise<DirectoryHandle>;
+  getFileHandle: (name: string) => Promise<FileHandle>;
+  resolve: (possibleDescendant: FileHandle) => Promise<string[] | null>;
+}

From f42f32e45a314c8230ec7e32c8a361b18adf7653 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 12:27:05 +0100
Subject: [PATCH 11/23] fix for netlify build error

---
 .../src/helpers/file-system-access.types.ts     | 17 +++--------------
 .../src/types/window-file-system-access.d.ts    |  9 +++++++++
 2 files changed, 12 insertions(+), 14 deletions(-)
 create mode 100644 apps/studio/src/types/window-file-system-access.d.ts

diff --git a/apps/studio/src/helpers/file-system-access.types.ts b/apps/studio/src/helpers/file-system-access.types.ts
index 1774b9847..67b540e43 100644
--- a/apps/studio/src/helpers/file-system-access.types.ts
+++ b/apps/studio/src/helpers/file-system-access.types.ts
@@ -1,14 +1,3 @@
-export interface FileHandle {
-  kind: 'file';
-  name: string;
-  getFile: () => Promise<File>;
-}
-
-export interface DirectoryHandle {
-  kind: 'directory';
-  name: string;
-  entries: () => AsyncIterableIterator<[string, DirectoryHandle | FileHandle]>;
-  getDirectoryHandle: (name: string) => Promise<DirectoryHandle>;
-  getFileHandle: (name: string) => Promise<FileHandle>;
-  resolve: (possibleDescendant: FileHandle) => Promise<string[] | null>;
-}
+/* eslint-disable no-undef */
+export type DirectoryHandle = FileSystemDirectoryHandle;
+export type FileHandle = FileSystemFileHandle;
diff --git a/apps/studio/src/types/window-file-system-access.d.ts b/apps/studio/src/types/window-file-system-access.d.ts
new file mode 100644
index 000000000..11a76f628
--- /dev/null
+++ b/apps/studio/src/types/window-file-system-access.d.ts
@@ -0,0 +1,9 @@
+/* eslint-disable no-undef */
+export {};
+
+declare global {
+  interface Window {
+    showDirectoryPicker: (options?: { mode?: 'read' | 'readwrite' }) => Promise<FileSystemDirectoryHandle>;
+    showOpenFilePicker: (options?: unknown) => Promise<FileSystemFileHandle[]>;
+  }
+}

From 0420839e1a36604ef15a58f5f4bcc09704a3f12f Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 12:53:45 +0100
Subject: [PATCH 12/23] fix for netlify build error

---
 apps/studio/src/state/documents.state.ts | 24 ++++++++++++++----------
 1 file changed, 14 insertions(+), 10 deletions(-)

diff --git a/apps/studio/src/state/documents.state.ts b/apps/studio/src/state/documents.state.ts
index 057a84a7c..bfdbc77f0 100644
--- a/apps/studio/src/state/documents.state.ts
+++ b/apps/studio/src/state/documents.state.ts
@@ -48,16 +48,20 @@ export const documentsState = create<DocumentsState & DocumentsActions>(set => (
   },
   updateDocument(uri: string, document: Partial<Document>) {
     set(state => ({
-      documents: {
-        ...state.documents,
-        [String(uri)]: {
-          uri: String(uri),
-          diagnostics: emptyDiagnostics,
-          valid: false,
-          ...state.documents[String(uri)] || {},
-          ...document,
-        }
-      }
+      documents: (() => {
+        const key = String(uri);
+        const existing = state.documents[key] || {};
+        const merged = { ...existing, ...document };
+        return {
+          ...state.documents,
+          [key]: {
+            ...merged,
+            uri: key,
+            diagnostics: merged.diagnostics ?? emptyDiagnostics,
+            valid: merged.valid ?? false,
+          },
+        };
+      })(),
     }));
   },
 }));

From fdb9a60c337e8e78bbedbfd992d83a4271379d31 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Fri, 6 Mar 2026 13:19:40 +0100
Subject: [PATCH 13/23] debug grantFolderAccess

---
 .../src/components/Modals/OpenFolderModal.tsx  | 18 +++++++++++-------
 apps/studio/src/services/editor.service.tsx    | 11 +++++++++++
 2 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/apps/studio/src/components/Modals/OpenFolderModal.tsx b/apps/studio/src/components/Modals/OpenFolderModal.tsx
index 9079d8369..fd7c5f016 100644
--- a/apps/studio/src/components/Modals/OpenFolderModal.tsx
+++ b/apps/studio/src/components/Modals/OpenFolderModal.tsx
@@ -8,13 +8,18 @@ import { useServices } from '../../services';
 export const OpenFolderModal = create(() => {
   const { editorSvc } = useServices();
 
-  const onSubmit = () => {
+  const onSubmit = async () => {
+    const toastId = 'open-folder';
     console.log('[DEBUG:ui] Open Folder — Continue clicked');
-    toast.promise(editorSvc.grantFolderAccess(), {
-      loading: 'Granting folder access...',
-      success: 'Folder access granted! File references will now be resolved.',
-      error: 'Failed to grant folder access.',
-    });
+    toast.loading('Granting folder access...', { id: toastId });
+    try {
+      await editorSvc.grantFolderAccess();
+      toast.success('Folder access granted! File references will now be resolved.', { id: toastId });
+    } catch (err: unknown) {
+      console.error('[DEBUG:ui] Open Folder failed', err);
+      const message = err instanceof Error ? err.message : 'Unknown error';
+      toast.error(`Failed to grant folder access: ${message}`, { id: toastId });
+    }
   };
 
   return (
@@ -44,4 +49,3 @@ export const OpenFolderModal = create(() => {
     </ConfirmModal>
   );
 });
-
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 77957406e..977e06098 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -244,11 +244,21 @@ export class EditorService extends AbstractService {
 
   async grantFolderAccess(): Promise<void> {
     const folderAccessToastId = 'folder-access';
+    if (!window.isSecureContext) {
+      throw new Error('Open Folder requires a secure context (HTTPS or localhost).');
+    }
+    if (
+      typeof window.showDirectoryPicker !== 'function' ||
+      typeof window.showOpenFilePicker !== 'function'
+    ) {
+      throw new Error('This browser context does not support the File System Access API.');
+    }
     let directoryHandle: DirectoryHandle;
     try {
       directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
     } catch (err: any) {
       if (err?.name === 'AbortError') return;
+      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
       throw err;
     }
 
@@ -263,6 +273,7 @@ export class EditorService extends AbstractService {
     } catch (err: any) {
       toast.dismiss(folderAccessToastId);
       if (err?.name === 'AbortError') return;
+      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
       throw err;
     }
 

From 633d79382389d24d59f630bbd03326715297f955 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Mon, 9 Mar 2026 08:34:07 +0100
Subject: [PATCH 14/23] rename import buttons

---
 .../src/components/Editor/EditorDropdown.tsx  | 14 ++++-----
 .../src/components/Editor/ImportDropdown.tsx  | 30 +++++++++----------
 2 files changed, 22 insertions(+), 22 deletions(-)

diff --git a/apps/studio/src/components/Editor/EditorDropdown.tsx b/apps/studio/src/components/Editor/EditorDropdown.tsx
index 327d5e559..da8ed4f5b 100644
--- a/apps/studio/src/components/Editor/EditorDropdown.tsx
+++ b/apps/studio/src/components/Editor/EditorDropdown.tsx
@@ -29,10 +29,10 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
     <button
       type="button"
       className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-      title="Open URL"
+      title="Import from URL"
       onClick={() => show(ImportURLModal)}
     >
-      Open URL
+      Import from URL
     </button>
   );
 
@@ -52,7 +52,7 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
   const importFileButton = (
     <label
       className="block px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 cursor-pointer"
-      title="Open File"
+      title="Import File"
     >
       <input
         ref={fileInputRef}
@@ -81,7 +81,7 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
           if (fileInputRef.current) fileInputRef.current.value = '';
         }}
       />
-      Open File
+      Import File
     </label>
   );
 
@@ -270,13 +270,13 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
       <ul className="bg-gray-800 text-md text-white">
         <div className="border-b border-gray-700">
           <li className="hover:bg-gray-900">
-            {importUrlButton}
+            {openFolderButton}
           </li>
           <li className="hover:bg-gray-900">
-            {importFileButton}
+            {importUrlButton}
           </li>
           <li className="hover:bg-gray-900">
-            {openFolderButton}
+            {importFileButton}
           </li>
           <li className="hover:bg-gray-900">
             {importBase64Button}
diff --git a/apps/studio/src/components/Editor/ImportDropdown.tsx b/apps/studio/src/components/Editor/ImportDropdown.tsx
index f943756b8..67737ab96 100644
--- a/apps/studio/src/components/Editor/ImportDropdown.tsx
+++ b/apps/studio/src/components/Editor/ImportDropdown.tsx
@@ -34,17 +34,28 @@ export const ImportDropdown: React.FC = () => {
           <button
             type="button"
             className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-            title="Open URL"
+            title="Open Folder"
+            onClick={() => show(OpenFolderModal)}
+          >
+            Open Folder
+          </button>
+        </li>
+
+        <li className="hover:bg-gray-900">
+          <button
+            type="button"
+            className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
+            title="Import from URL"
             onClick={() => show(ImportURLModal)}
           >
-                Open URL
+            Import from URL
           </button>
         </li>
 
         <li className="hover:bg-gray-900">
           <label
             className="block px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 cursor-pointer"
-            title="Open File"
+            title="Import File"
           >
             <input
               ref={fileInputRef}
@@ -73,21 +84,10 @@ export const ImportDropdown: React.FC = () => {
                 if (fileInputRef.current) fileInputRef.current.value = '';
               }}
             />
-            Open File
+            Import File
           </label>
         </li>
 
-        <li className="hover:bg-gray-900">
-          <button
-            type="button"
-            className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-            title="Open Folder"
-            onClick={() => show(OpenFolderModal)}
-          >
-            Open Folder
-          </button>
-        </li>
-
         <li className="hover:bg-gray-900">
           <button
             type="button"

From d0a393b21359d39ef847f0376f4209b9e8ba0d63 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Mon, 9 Mar 2026 10:15:10 +0100
Subject: [PATCH 15/23] reorder buttons

---
 apps/studio/src/components/Editor/EditorDropdown.tsx |  4 ++--
 apps/studio/src/components/Editor/ImportDropdown.tsx | 12 ++++++------
 2 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/apps/studio/src/components/Editor/EditorDropdown.tsx b/apps/studio/src/components/Editor/EditorDropdown.tsx
index da8ed4f5b..5d989e4c3 100644
--- a/apps/studio/src/components/Editor/EditorDropdown.tsx
+++ b/apps/studio/src/components/Editor/EditorDropdown.tsx
@@ -270,10 +270,10 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
       <ul className="bg-gray-800 text-md text-white">
         <div className="border-b border-gray-700">
           <li className="hover:bg-gray-900">
-            {openFolderButton}
+            {importUrlButton}
           </li>
           <li className="hover:bg-gray-900">
-            {importUrlButton}
+            {openFolderButton}
           </li>
           <li className="hover:bg-gray-900">
             {importFileButton}
diff --git a/apps/studio/src/components/Editor/ImportDropdown.tsx b/apps/studio/src/components/Editor/ImportDropdown.tsx
index 67737ab96..7f183eef8 100644
--- a/apps/studio/src/components/Editor/ImportDropdown.tsx
+++ b/apps/studio/src/components/Editor/ImportDropdown.tsx
@@ -34,10 +34,10 @@ export const ImportDropdown: React.FC = () => {
           <button
             type="button"
             className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-            title="Open Folder"
-            onClick={() => show(OpenFolderModal)}
+            title="Import from URL"
+            onClick={() => show(ImportURLModal)}
           >
-            Open Folder
+            Import from URL
           </button>
         </li>
 
@@ -45,10 +45,10 @@ export const ImportDropdown: React.FC = () => {
           <button
             type="button"
             className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150"
-            title="Import from URL"
-            onClick={() => show(ImportURLModal)}
+            title="Open Folder"
+            onClick={() => show(OpenFolderModal)}
           >
-            Import from URL
+            Open Folder
           </button>
         </li>
 

From 40b1abef999fda89c2813ab81ae677cb4f9dbd25 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Mon, 9 Mar 2026 19:41:20 +0100
Subject: [PATCH 16/23] write functionality

---
 .../src/components/Editor/EditorDropdown.tsx  |   53 +-
 .../src/components/Editor/EditorSidebar.tsx   |   13 +-
 .../src/components/Editor/MonacoWrapper.tsx   |   11 +-
 .../src/components/Editor/SaveDropdown.tsx    |  136 +-
 .../Modals/Settings/SettingsModal.tsx         |   53 +-
 .../src/components/Terminal/TerminalInfo.tsx  |   17 +-
 apps/studio/src/services/editor.service.tsx   | 1378 ++++++++---------
 apps/studio/src/services/parser.service.ts    |    2 +-
 apps/studio/src/state/settings.state.ts       |   10 +-
 .../src/types/window-file-system-access.d.ts  |    1 +
 10 files changed, 750 insertions(+), 924 deletions(-)

diff --git a/apps/studio/src/components/Editor/EditorDropdown.tsx b/apps/studio/src/components/Editor/EditorDropdown.tsx
index 5d989e4c3..4e885d4e3 100644
--- a/apps/studio/src/components/Editor/EditorDropdown.tsx
+++ b/apps/studio/src/components/Editor/EditorDropdown.tsx
@@ -23,7 +23,8 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
   const isInvalidDocument = !useDocumentsState(state => {
     return state.documents['asyncapi']?.valid
   });
-  const language = useFilesState(state => state.files['asyncapi'].language);
+  const file = useFilesState(state => state.files['asyncapi']);
+  const language = file.language;
 
   const importUrlButton = (
     <button
@@ -123,12 +124,10 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
     <button
       type="button"
       className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 disabled:cursor-not-allowed"
-      title={`Save as ${language === 'yaml' ? 'YAML' : 'JSON'}`}
+      title="Save"
       onClick={() => {
         toast.promise(
-          language === 'yaml'
-            ? editorSvc.saveAsYaml()
-            : editorSvc.saveAsJSON(),
+          editorSvc.saveCurrentFile(),
           {
             loading: 'Saving...',
             success: (
@@ -148,46 +147,9 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
           },
         );
       }}
-      disabled={isInvalidDocument}
-    >
-      Save as {language === 'yaml' ? 'YAML' : 'JSON'}
-    </button>
-  );
-
-  const convertLangAndSaveButton = (
-    <button
-      type="button"
-      className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 disabled:cursor-not-allowed"
-      title={`Convert and save as ${
-        language === 'yaml' ? 'JSON' : 'YAML'
-      }`}
-      onClick={() => {
-        toast.promise(
-          language === 'yaml'
-            ? editorSvc.saveAsJSON()
-            : editorSvc.saveAsYaml(),
-          {
-            loading: 'Saving...',
-            success: (
-              <div>
-                <span className="block text-bold">
-                  Document succesfully converted and saved!
-                </span>
-              </div>
-            ),
-            error: (
-              <div>
-                <span className="block text-bold text-red-400">
-                  Failed to convert and save document.
-                </span>
-              </div>
-            ),
-          },
-        );
-      }}
-      disabled={isInvalidDocument}
+      disabled={!file.modified}
     >
-      Convert and save as {language === 'yaml' ? 'JSON' : 'YAML'}
+      Save
     </button>
   );
 
@@ -299,9 +261,6 @@ export const EditorDropdown: React.FunctionComponent<EditorDropdownProps> = () =
           <li className="hover:bg-gray-900">
             {saveFileButton}
           </li>
-          <li className="hover:bg-gray-900">
-            {convertLangAndSaveButton}
-          </li>
         </div>
         <div>
           <li className="hover:bg-gray-900">
diff --git a/apps/studio/src/components/Editor/EditorSidebar.tsx b/apps/studio/src/components/Editor/EditorSidebar.tsx
index 79a049ecf..cecd7f004 100644
--- a/apps/studio/src/components/Editor/EditorSidebar.tsx
+++ b/apps/studio/src/components/Editor/EditorSidebar.tsx
@@ -4,7 +4,7 @@ import { useFilesState } from '../../state';
 import { ShareButton } from './ShareButton';
 import { ImportDropdown } from './ImportDropdown';
 import { GenerateDropdown } from './GenerateDropdown';
-import { SaveDropdown } from './SaveDropdown';
+import { SaveButton } from './SaveDropdown';
 import { ConvertDropdown } from './ConvertDropdown';
 
 interface EditorSidebarProps {}
@@ -12,17 +12,22 @@ interface EditorSidebarProps {}
 export const EditorSidebar: React.FunctionComponent<
   EditorSidebarProps
 > = () => {
-  const { source, from } = useFilesState((state) => state.files['asyncapi']);
+  const { source, from, localPath, uri } = useFilesState((state) => state.files['asyncapi']);
 
   let documentFromText = '';
   if (from === 'storage') {
     documentFromText = 'From localStorage';
+  } else if (from === 'file') {
+    const path = source || localPath || uri;
+    documentFromText = path ? `From local file ${path}` : 'From local file';
+  } else if (from === 'url') {
+    documentFromText = `From URL ${source || uri || ''}`.trim();
   } else if (from === 'base64') {
     documentFromText = 'From Base64';
   } else if (from === 'share') {
     documentFromText = 'From Shared';
   } else {
-    documentFromText = `From URL ${source}`;
+    documentFromText = source || uri ? `From ${source || uri}` : 'From unknown source';
   }
 
   return (
@@ -49,7 +54,7 @@ export const EditorSidebar: React.FunctionComponent<
               <GenerateDropdown />
             </li>
             <li>
-              <SaveDropdown />
+              <SaveButton />
             </li>
             <li>
               <ConvertDropdown />
diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index e264bc630..4c0cf1e3c 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -4,7 +4,7 @@ import MonacoEditor from '@monaco-editor/react';
 
 import { debounce } from '@/helpers';
 import { useServices } from '@/services';
-import { useFilesState, useSettingsState } from '@/state';
+import { useFilesState } from '@/state';
 
 import type { EditorProps as MonacoEditorProps } from '@monaco-editor/react';
 
@@ -12,18 +12,17 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
   ...props
 }) => {
   const { editorSvc } = useServices();
-  const { autoSaving, savingDelay } = useSettingsState(state => state.editor);
   const file = useFilesState(state => state.files['asyncapi']);
+  const editorChangeDebounceMs = 300;
 
   const onChange = useMemo(() => {
     return debounce((v: string) => {
       // Preserve the current source URL instead of setting to undefined
       const currentSource = file?.source;
-      editorSvc.updateState({ content: v, file: { source: currentSource } });
-      autoSaving && editorSvc.saveToLocalStorage(v, false);
+      editorSvc.updateState({ content: v, file: { source: currentSource, modified: true } });
       // subscribeToFiles will trigger a re-parse when content changes
-    }, savingDelay);
-  }, [autoSaving, savingDelay, file?.source, editorSvc]);
+    }, editorChangeDebounceMs);
+  }, [file?.source, editorSvc]);
 
   if (!file) {
     return null;
diff --git a/apps/studio/src/components/Editor/SaveDropdown.tsx b/apps/studio/src/components/Editor/SaveDropdown.tsx
index 53bc6e788..6f06aae72 100644
--- a/apps/studio/src/components/Editor/SaveDropdown.tsx
+++ b/apps/studio/src/components/Editor/SaveDropdown.tsx
@@ -2,101 +2,57 @@ import React from 'react';
 import toast from 'react-hot-toast';
 import { FaSave } from 'react-icons/fa';
 
-import { Dropdown, Tooltip } from '../common';
+import { Tooltip } from '../common';
 import { useServices } from '@/services';
-import { useDocumentsState, useFilesState } from '../../state';
+import { useFilesState } from '../../state';
 
-export const SaveDropdown: React.FC = () => {
+export const SaveButton: React.FC = () => {
   const { editorSvc } = useServices();
-  const isInvalidDocument = !useDocumentsState(state => 
-    state.documents['asyncapi']?.valid
-  );
-  const language = useFilesState(state => state.files['asyncapi'].language);
+  const file = useFilesState(state => state.files['asyncapi']);
+  const isDirectSave = file?.from === 'file' && !!file?.fileHandle;
+  const baseLabel = isDirectSave ? 'Save' : 'Export';
+  const tooltipText = file?.modified ? baseLabel : `${baseLabel} (saved)`;
 
   return (
-    <Dropdown
-      opener={
-        <Tooltip content="Save" placement="top" hideOnClick={true}>
-          <div className="bg-inherit">
-            <FaSave />
-          </div>
-        </Tooltip>
-      }
-      buttonHoverClassName="text-gray-500 hover:text-white"
-      dataTest="button-save-dropdown"
-    >
-      <ul className="bg-gray-800 text-md text-white">
-        <li className="hover:bg-gray-900">
-          <button
-            type="button"
-            className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 disabled:cursor-not-allowed"
-            title={`Save as ${language === 'yaml' ? 'YAML' : 'JSON'}`}
-            onClick={() => {
-              toast.promise(
-                language === 'yaml'
-                  ? editorSvc.saveAsYaml()
-                  : editorSvc.saveAsJSON(),
-                {
-                  loading: 'Saving...',
-                  success: (
-                    <div>
-                      <span className="block text-bold">
-                        Document succesfully saved!
-                      </span>
-                    </div>
-                  ),
-                  error: (
-                    <div>
-                      <span className="block text-bold text-red-400">
-                        Failed to save document.
-                      </span>
-                    </div>
-                  ),
-                },
-              );
-            }}
-            disabled={isInvalidDocument}
-          >
-            Save as {language === 'yaml' ? 'YAML' : 'JSON'}
-          </button>
-        </li>
-        <li className="hover:bg-gray-900">
-          <button
-            type="button"
-            className="px-4 py-1 w-full text-left text-sm rounded-md focus:outline-none transition ease-in-out duration-150 disabled:cursor-not-allowed"
-            title={`Convert and save as ${language === 'yaml' ? 'JSON' : 'YAML'}`}
-            onClick={() => {
-              toast.promise(
-                language === 'yaml'
-                  ? editorSvc.saveAsJSON()
-                  : editorSvc.saveAsYaml(),
-                {
-                  loading: 'Saving...',
-                  success: (
-                    <div>
-                      <span className="block text-bold">
-                        Document succesfully converted and saved!
-                      </span>
-                    </div>
-                  ),
-                  error: (
-                    <div>
-                      <span className="block text-bold text-red-400">
-                        Failed to convert and save document.
-                      </span>
-                    </div>
-                  ),
-                },
-              );
-            }}
-            disabled={isInvalidDocument}
-          >
-            Convert and save as {language === 'yaml' ? 'JSON' : 'YAML'}
-          </button>
-        </li>
-       
-      </ul>
-    </Dropdown>
+    <Tooltip content={tooltipText} placement="top" hideOnClick={true}>
+      <button
+        type="button"
+        className="bg-inherit px-2 disabled:cursor-not-allowed"
+        title={tooltipText}
+        onClick={() => {
+          toast.promise(
+            editorSvc.saveCurrentFile(),
+            {
+              loading: 'Saving...',
+              success: (
+                <div>
+                  <span className="block text-bold">
+                    Document succesfully saved!
+                  </span>
+                </div>
+              ),
+              error: (
+                <div>
+                  <span className="block text-bold text-red-400">
+                    Failed to save document.
+                  </span>
+                </div>
+              ),
+            },
+          );
+        }}
+        disabled={!file?.modified}
+        data-test="button-save-dropdown"
+      >
+        <FaSave
+          className={
+            !file?.modified
+              ? 'text-gray-600'
+              : 'text-gray-500 hover:text-white'
+          }
+        />
+      </button>
+    </Tooltip>
   );
 };
 
diff --git a/apps/studio/src/components/Modals/Settings/SettingsModal.tsx b/apps/studio/src/components/Modals/Settings/SettingsModal.tsx
index 5ee4a9338..29e56f8fc 100644
--- a/apps/studio/src/components/Modals/Settings/SettingsModal.tsx
+++ b/apps/studio/src/components/Modals/Settings/SettingsModal.tsx
@@ -55,8 +55,6 @@ export const SettingsModal = create<SettingsModalProps>(({ activeTab = 'editor'
   const settings = settingsSvc.get();
   const modal = useModal();
 
-  const [autoSaving, setAutoSaving] = useState(settings.editor.autoSaving);
-  const [savingDelay, setSavingDelay] = useState(settings.editor.savingDelay);
   const [governanceWarnings, setGovernanceWarnings] = useState(settings.governance.show.warnings);
   const [governanceInformations, setGovernanceInformations] = useState(settings.governance.show.informations);
   const [governanceHints, setGovernanceHints] = useState(settings.governance.show.hints);
@@ -65,10 +63,6 @@ export const SettingsModal = create<SettingsModalProps>(({ activeTab = 'editor'
 
   const createNewState = (): SettingsState => {
     return {
-      editor: {
-        autoSaving,
-        savingDelay,
-      },
       governance: {
         show: {
           warnings: governanceWarnings,
@@ -86,7 +80,7 @@ export const SettingsModal = create<SettingsModalProps>(({ activeTab = 'editor'
     const newState = createNewState();
     const isThisSameObjects = settingsSvc.isEqual(newState);
     setConfirmDisabled(isThisSameObjects);
-  }, [autoSaving, savingDelay, autoRendering, governanceWarnings, governanceInformations, governanceHints]);
+  }, [autoRendering, governanceWarnings, governanceInformations, governanceHints]);
 
   const onCancel = useCallback(() => {
     modal.hide();
@@ -112,49 +106,8 @@ export const SettingsModal = create<SettingsModalProps>(({ activeTab = 'editor'
       tab: <span>Editor</span>,
       content: (
         <div>
-          <div className="flex flex-col mt-4 text-sm">
-            <div className="flex flex-row content-center justify-between">
-              <label
-                htmlFor="settings-auto-saving"
-                className="flex justify-right items-center w-1/2 content-center font-medium text-gray-700"
-              >
-                Auto saving
-              </label>
-              <Switch
-                toggle={autoSaving}
-                onChange={(v) => setAutoSaving(v)}
-              />
-            </div>
-            <div className='text-gray-400 text-xs'>
-              Save automatically after each change in the document or manually.
-            </div>
-          </div>
-          <div className="flex flex-col mt-4 text-sm">
-            <div className="flex flex-row content-center justify-between">
-              <label
-                htmlFor="settings-template-delay"
-                className="flex justify-right items-center w-1/2 content-center font-medium text-gray-700"
-              >
-                Delay (in miliseconds)
-              </label>
-              <select
-                name="settings-template-delay"
-                className="shadow-sm focus:ring-pink-500 focus:border-pink-500 w-1/4 block sm:text-sm rounded-md py-2 px-1 text-gray-700 border-pink-300 border-2"
-                onChange={e => setSavingDelay(JSON.parse(e.target.value))}
-                value={autoSaving ? savingDelay : ''}
-                disabled={!autoSaving}
-              >
-                <option value="">Please Select</option>
-                {[250, 500, 625, 750, 875, 1000].map(v => (
-                  <option key={v} value={v}>
-                    {v}
-                  </option>
-                ))}
-              </select>
-            </div>
-            <div className='text-gray-400 text-xs -mt-2'>
-              Delay in saving the modified document.
-            </div>
+          <div className="text-sm text-gray-400 mt-4">
+            No editor settings available.
           </div>
         </div>
       ),
diff --git a/apps/studio/src/components/Terminal/TerminalInfo.tsx b/apps/studio/src/components/Terminal/TerminalInfo.tsx
index e62064626..446bbf4c3 100644
--- a/apps/studio/src/components/Terminal/TerminalInfo.tsx
+++ b/apps/studio/src/components/Terminal/TerminalInfo.tsx
@@ -5,7 +5,7 @@ import { show } from '@ebay/nice-modal-react';
 import { ConvertToLatestModal } from '../Modals';
 
 import { useServices } from '../../services';
-import { useAppState, useDocumentsState, useFilesState, useSettingsState } from '../../state';
+import { useAppState, useDocumentsState, useFilesState } from '../../state';
 
 import type { FunctionComponent } from 'react';
 
@@ -15,7 +15,6 @@ export const TerminalInfo: FunctionComponent<TerminalInfoProps> = () => {
   const { specificationSvc } = useServices();
   const file = useFilesState(state => state.files['asyncapi']);
   const document = useDocumentsState(state => state.documents['asyncapi']);
-  const autoSaving = useSettingsState(state => state.editor.autoSaving);
   const liveServer = useAppState(state => state.liveServer);
 
   const onNonLatestClick = useCallback((e: {stopPropagation: ()=>void}) => {
@@ -76,23 +75,13 @@ export const TerminalInfo: FunctionComponent<TerminalInfoProps> = () => {
           <span>Valid</span>
         </div>
       )}
-      {!autoSaving && file.modified && (
-        <div className="ml-3">
-          <span className="text-yellow-500">
-            <svg xmlns="http://www.w3.org/2000/svg" className="inline-block h-5 w-5 mr-1 -mt-0.5" viewBox="0 0 20 20" fill="currentColor">
-              <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
-            </svg>
-          </span>
-          <span>Modified</span>
-        </div>
-      )}
       <div className="ml-3">
-        <span className="text-blue-400">
+        <span className={file.modified ? 'text-yellow-500' : 'text-green-500'}>
           <svg xmlns="http://www.w3.org/2000/svg" className="inline-block h-5 w-5 mr-1 -mt-0.5" viewBox="0 0 20 20" fill="currentColor">
             <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
           </svg>
         </span>
-        <span>{autoSaving ? 'Autosave: On' : 'Autosave: Off'}</span>
+        <span>{file.modified ? 'Modified' : 'Unchanged'}</span>
       </div>
       {actualVersion !== latestVersion && document.valid === true && (
         <div className="ml-3" 
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 977e06098..6c7f740ac 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -1,316 +1,320 @@
-import { AbstractService } from './abstract.service';
-
+import { AbstractService } from './abstract.service';
+
 import { KeyMod, KeyCode } from 'monaco-editor/esm/vs/editor/editor.api';
 import { DiagnosticSeverity } from '@asyncapi/parser';
 import { Range, MarkerSeverity } from 'monaco-editor/esm/vs/editor/editor.api';
 import toast from 'react-hot-toast';
-import fileDownload from 'js-file-download';
-
-import { appState, documentsState, filesState, settingsState } from '@/state';
-import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
-
-import type * as monacoAPI from 'monaco-editor/esm/vs/editor/editor.api';
-import type { Diagnostic } from '@asyncapi/parser';
-import type { AsyncAPIConvertVersion } from '@asyncapi/converter';
-import type { File } from '@/state/files.state';
-
-export interface UpdateState {
-  content: string;
-  updateModel?: boolean;
-  sendToServer?: boolean;
-  file?: Partial<File>;
-} 
-
-export class EditorService extends AbstractService {
-  private created = false;
-  private decorations: Map<string, string[]> = new Map();
-  private instance: monacoAPI.editor.IStandaloneCodeEditor | undefined;
-
-  override onInit() {
-    this.subcribeToDocuments();
-  }
 
-  async onDidCreate(editor: monacoAPI.editor.IStandaloneCodeEditor) {
-    if (this.created) {
-      return;
-    }
-    this.created = true;
-    this.instance = editor;
-
-    // parse on first run - only when document is undefined
-    const document = documentsState.getState().documents.asyncapi;
-    if (!document) {
-      await this.svcs.parserSvc.parse('asyncapi', editor.getValue());
-    } else {
-      this.applyMarkersAndDecorations(document.diagnostics.filtered);
-    }
-    
+import { appState, documentsState, filesState } from '@/state';
+import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
+
+import type * as monacoAPI from 'monaco-editor/esm/vs/editor/editor.api';
+import type { Diagnostic } from '@asyncapi/parser';
+import type { AsyncAPIConvertVersion } from '@asyncapi/converter';
+import type { File } from '@/state/files.state';
+
+export interface UpdateState {
+  content: string;
+  updateModel?: boolean;
+  sendToServer?: boolean;
+  file?: Partial<File>;
+} 
+
+export class EditorService extends AbstractService {
+  private created = false;
+  private decorations: Map<string, string[]> = new Map();
+  private instance: monacoAPI.editor.IStandaloneCodeEditor | undefined;
+
+  override onInit() {
+    this.subcribeToDocuments();
+  }
+
+  async onDidCreate(editor: monacoAPI.editor.IStandaloneCodeEditor) {
+    if (this.created) {
+      return;
+    }
+    this.created = true;
+    this.instance = editor;
+
+    // parse on first run - only when document is undefined
+    const document = documentsState.getState().documents.asyncapi;
+    if (!document) {
+      await this.svcs.parserSvc.parse('asyncapi', editor.getValue());
+    } else {
+      this.applyMarkersAndDecorations(document.diagnostics.filtered);
+    }
+    
     // apply save command
     editor.addCommand(
       KeyMod.CtrlCmd | KeyCode.KeyS,
-      () => this.saveToLocalStorage(),
+      () => {
+        this.saveCurrentFile().catch((err) => {
+          console.error(err);
+          toast.error('Failed to save document.');
+        });
+      },
     );
-    
-    appState.setState({ initialized: true });
-  }
-
-  get editor(): monacoAPI.editor.IStandaloneCodeEditor | undefined {
-    return this.instance;
-  }
-
-  get value(): string {
-    return this.editor?.getModel()?.getValue() as string;
-  }
-
-  private getFileNameFromUri(uri: string): string {
-    if (!uri) return 'asyncapi';
-    const normalized = uri.replace(/\\/g, '/');
-    const parts = normalized.split('/');
-    return parts[parts.length - 1] || uri;
-  }
-
-  private inferLanguageFromUri(uri: string, content?: string): 'json' | 'yaml' {
-    const byContent = content ? this.svcs.formatSvc.retrieveLangauge(content) : undefined;
-    if (byContent === 'json' || byContent === 'yaml') {
-      return byContent;
-    }
-    const lower = uri.toLowerCase();
-    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
-      return 'json';
-    }
-    return 'yaml';
-  }
-
-  private isAsyncApiContent(content: string): boolean {
-    const trimmed = String(content || '').trim();
-    if (!trimmed) return false;
-    if (trimmed.startsWith('{')) {
-      try {
-        const parsed = JSON.parse(trimmed);
-        return !!parsed?.asyncapi;
-      } catch {
-        return false;
-      }
-    }
-    return (/^asyncapi\s*:/m).test(trimmed);
-  }
-
-  private hasUnsupportedEditorExtension(uri: string): boolean {
-    const blocked = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2'];
-    const path = uri.split('?')[0].toLowerCase();
-    return blocked.some((ext) => path.endsWith(ext));
-  }
-
-  async switchToFile(uri: string): Promise<void> {
-    const { files, setFileTreeLoading, setActiveFile, updateFile } = filesState.getState();
-    const target = files[String(uri)];
-    if (!target) {
-      return;
-    }
-
-    if (this.hasUnsupportedEditorExtension(uri)) {
-      toast.error('This file type is not supported in the editor.');
-      return;
-    }
-
-    setFileTreeLoading(true);
-    try {
-      let content = target.content;
-      const fileHandle = target.fileHandle;
-      if (!content && fileHandle) {
-        const file = await fileHandle.getFile();
-        content = await file.text();
-      }
-      if (!content && (/^https?:\/\//).test(uri)) {
-        content = await fetch(uri).then((res) => res.text());
-      }
-
-      if (typeof content !== 'string') {
-        content = '';
-      }
-
-      const language = this.inferLanguageFromUri(uri, content);
-      updateFile(uri, {
-        content,
-        language,
-        name: target.name || this.getFileNameFromUri(uri),
-        isAsyncApiDocument: this.isAsyncApiContent(content),
-        stat: { mtime: Date.now() },
-      });
-      setActiveFile(uri);
-      this.updateState({
-        content,
-        updateModel: true,
-        sendToServer: false,
-        file: {
-          source: target.source,
-          from: target.from,
-          language,
-          fileHandle,
-          directoryHandle: target.directoryHandle,
-          localPath: target.localPath,
-          name: target.name || this.getFileNameFromUri(uri),
-          isAsyncApiDocument: this.isAsyncApiContent(content),
-          stat: { mtime: Date.now() },
-        },
-      });
-    } finally {
-      setFileTreeLoading(false);
-    }
-  }
-
-  private async collectLocalProjectFiles(
-    directoryHandle: DirectoryHandle,
-    basePath = '',
-    rootName = directoryHandle.name,
-  ): Promise<Record<string, File>> {
-    const files: Record<string, File> = {};
-
-    for await (const [, entry] of directoryHandle.entries()) {
-      if (entry.kind === 'directory') {
-        const childPath = basePath ? `${basePath}/${entry.name}` : entry.name;
-        const nested = await this.collectLocalProjectFiles(entry, childPath, rootName);
-        Object.assign(files, nested);
-      } else if (entry.kind === 'file') {
-        const localPath = basePath ? `${basePath}/${entry.name}` : entry.name;
-        const fileHandle = entry as FileHandle;
-        try {
-          const file = await fileHandle.getFile();
-          const content = await file.text();
-          const language = this.inferLanguageFromUri(localPath, content);
-          files[localPath] = {
-            uri: localPath,
-            name: this.getFileNameFromUri(localPath),
-            content,
-            from: 'file',
-            source: `${rootName}/${localPath}`,
-            language,
-            modified: false,
-            directoryHandle,
-            fileHandle,
-            localPath,
-            isAsyncApiDocument: this.isAsyncApiContent(content),
-            stat: { mtime: Date.now() },
-          };
-        } catch (err) {
-          console.error('[DEBUG:editor] Failed to read local file for tree', localPath, err);
-        }
-      }
-    }
-
-    return files;
-  }
-
-  updateState({
-    content,
-    updateModel = false,
-    sendToServer = true,
-    file = {},
-  }: UpdateState) {
-    const currentContent = filesState.getState().files['asyncapi']?.content;
-    if (currentContent === content || typeof content !== 'string') {
-      return;
-    }
-
-    const language = file.language || this.svcs.formatSvc.retrieveLangauge(content);
-    if (!language) {
-      return;
-    }
-
-    if (sendToServer) {
-      this.svcs.socketClientSvc.send('file:update', { code: content });
-    }
-
-    if (updateModel && this.editor) {
-      const model = this.editor.getModel();
-      if (model) {
-        model.setValue(content);
-      }
-    }
-
+    
+    appState.setState({ initialized: true });
+  }
+
+  get editor(): monacoAPI.editor.IStandaloneCodeEditor | undefined {
+    return this.instance;
+  }
+
+  get value(): string {
+    return this.editor?.getModel()?.getValue() as string;
+  }
+
+  private getFileNameFromUri(uri: string): string {
+    if (!uri) return 'asyncapi';
+    const normalized = uri.replace(/\\/g, '/');
+    const parts = normalized.split('/');
+    return parts[parts.length - 1] || uri;
+  }
+
+  private inferLanguageFromUri(uri: string, content?: string): 'json' | 'yaml' {
+    const byContent = content ? this.svcs.formatSvc.retrieveLangauge(content) : undefined;
+    if (byContent === 'json' || byContent === 'yaml') {
+      return byContent;
+    }
+    const lower = uri.toLowerCase();
+    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
+      return 'json';
+    }
+    return 'yaml';
+  }
+
+  private isAsyncApiContent(content: string): boolean {
+    const trimmed = String(content || '').trim();
+    if (!trimmed) return false;
+    if (trimmed.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return !!parsed?.asyncapi;
+      } catch {
+        return false;
+      }
+    }
+    return (/^asyncapi\s*:/m).test(trimmed);
+  }
+
+  private hasUnsupportedEditorExtension(uri: string): boolean {
+    const blocked = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.ico', '.pdf', '.zip', '.tar', '.gz', '.woff', '.woff2'];
+    const path = uri.split('?')[0].toLowerCase();
+    return blocked.some((ext) => path.endsWith(ext));
+  }
+
+  async switchToFile(uri: string): Promise<void> {
+    const { files, setFileTreeLoading, setActiveFile, updateFile } = filesState.getState();
+    const target = files[String(uri)];
+    if (!target) {
+      return;
+    }
+
+    if (this.hasUnsupportedEditorExtension(uri)) {
+      toast.error('This file type is not supported in the editor.');
+      return;
+    }
+
+    setFileTreeLoading(true);
+    try {
+      let content = target.content;
+      const fileHandle = target.fileHandle;
+      if (!content && fileHandle) {
+        const file = await fileHandle.getFile();
+        content = await file.text();
+      }
+      if (!content && (/^https?:\/\//).test(uri)) {
+        content = await fetch(uri).then((res) => res.text());
+      }
+
+      if (typeof content !== 'string') {
+        content = '';
+      }
+
+      const language = this.inferLanguageFromUri(uri, content);
+      updateFile(uri, {
+        content,
+        language,
+        name: target.name || this.getFileNameFromUri(uri),
+        isAsyncApiDocument: this.isAsyncApiContent(content),
+        stat: { mtime: Date.now() },
+      });
+      setActiveFile(uri);
+      this.updateState({
+        content,
+        updateModel: true,
+        sendToServer: false,
+        file: {
+          source: target.source,
+          from: target.from,
+          language,
+          fileHandle,
+          directoryHandle: target.directoryHandle,
+          localPath: target.localPath,
+          name: target.name || this.getFileNameFromUri(uri),
+          isAsyncApiDocument: this.isAsyncApiContent(content),
+          stat: { mtime: Date.now() },
+        },
+      });
+    } finally {
+      setFileTreeLoading(false);
+    }
+  }
+
+  private async collectLocalProjectFiles(
+    directoryHandle: DirectoryHandle,
+    basePath = '',
+    rootName = directoryHandle.name,
+  ): Promise<Record<string, File>> {
+    const files: Record<string, File> = {};
+
+    for await (const [, entry] of directoryHandle.entries()) {
+      if (entry.kind === 'directory') {
+        const childPath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        const nested = await this.collectLocalProjectFiles(entry, childPath, rootName);
+        Object.assign(files, nested);
+      } else if (entry.kind === 'file') {
+        const localPath = basePath ? `${basePath}/${entry.name}` : entry.name;
+        const fileHandle = entry as FileHandle;
+        try {
+          const file = await fileHandle.getFile();
+          const content = await file.text();
+          const language = this.inferLanguageFromUri(localPath, content);
+          files[localPath] = {
+            uri: localPath,
+            name: this.getFileNameFromUri(localPath),
+            content,
+            from: 'file',
+            source: `${rootName}/${localPath}`,
+            language,
+            modified: false,
+            directoryHandle,
+            fileHandle,
+            localPath,
+            isAsyncApiDocument: this.isAsyncApiContent(content),
+            stat: { mtime: Date.now() },
+          };
+        } catch (err) {
+          console.error('[DEBUG:editor] Failed to read local file for tree', localPath, err);
+        }
+      }
+    }
+
+    return files;
+  }
+
+  updateState({
+    content,
+    updateModel = false,
+    sendToServer = true,
+    file = {},
+  }: UpdateState) {
+    const currentContent = filesState.getState().files['asyncapi']?.content;
+    if (currentContent === content || typeof content !== 'string') {
+      return;
+    }
+
+    const language = file.language || this.svcs.formatSvc.retrieveLangauge(content);
+    if (!language) {
+      return;
+    }
+
+    if (sendToServer) {
+      this.svcs.socketClientSvc.send('file:update', { code: content });
+    }
+
+    if (updateModel && this.editor) {
+      const model = this.editor.getModel();
+      if (model) {
+        model.setValue(content);
+      }
+    }
+
     const { updateFile } = filesState.getState();
     updateFile('asyncapi', {
       language,
       content,
-      modified: this.getFromLocalStorage() !== content,
+      modified: file.modified ?? true,
       ...file,
     });
   }
-
-  async convertSpec(version?: AsyncAPIConvertVersion | string) {
-    const converted = await this.svcs.converterSvc.convert(this.value, version as AsyncAPIConvertVersion);
-    this.updateState({ content: converted, updateModel: true });
-  }
-
-  async grantFolderAccess(): Promise<void> {
-    const folderAccessToastId = 'folder-access';
-    if (!window.isSecureContext) {
-      throw new Error('Open Folder requires a secure context (HTTPS or localhost).');
-    }
-    if (
-      typeof window.showDirectoryPicker !== 'function' ||
-      typeof window.showOpenFilePicker !== 'function'
-    ) {
-      throw new Error('This browser context does not support the File System Access API.');
-    }
-    let directoryHandle: DirectoryHandle;
-    try {
-      directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
-    } catch (err: any) {
-      if (err?.name === 'AbortError') return;
-      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
-      throw err;
-    }
-
-    toast.loading('Please select the AsyncAPI file within the folder...', { id: folderAccessToastId });
-    let fileHandle: FileHandle;
-    try {
-      const [handle] = await window.showOpenFilePicker({
-        types: [{ description: 'AsyncAPI files', accept: { 'text/*': ['.yaml', '.yml', '.json'] } }],
-        multiple: false,
-      });
-      fileHandle = handle;
-    } catch (err: any) {
-      toast.dismiss(folderAccessToastId);
-      if (err?.name === 'AbortError') return;
-      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
-      throw err;
-    }
-
-    const pathParts = await directoryHandle.resolve(fileHandle);
-    if (!pathParts) {
-      toast.dismiss(folderAccessToastId);
-      toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
-      return;
-    }
-
-    const localPath = pathParts.join('/');
-    const files = await this.collectLocalProjectFiles(directoryHandle);
-    const selectedFile = await fileHandle.getFile();
-    const selectedContent = await selectedFile.text();
-    const selectedLanguage = this.inferLanguageFromUri(localPath, selectedContent);
-
-    files[localPath] = {
-      uri: localPath,
-      name: this.getFileNameFromUri(localPath),
-      content: selectedContent,
-      language: selectedLanguage,
-      from: 'file',
-      source: `${directoryHandle.name}/${localPath}`,
-      directoryHandle,
-      fileHandle,
-      localPath,
-      modified: false,
-      isAsyncApiDocument: this.isAsyncApiContent(selectedContent),
-      stat: { mtime: Date.now() },
-    };
-
-    filesState.getState().setProjectFiles(files, {
-      activeFileUri: localPath,
-      fileTreeMode: 'local',
-      projectRoot: directoryHandle.name,
-    });
-
+
+  async convertSpec(version?: AsyncAPIConvertVersion | string) {
+    const converted = await this.svcs.converterSvc.convert(this.value, version as AsyncAPIConvertVersion);
+    this.updateState({ content: converted, updateModel: true });
+  }
+
+  async grantFolderAccess(): Promise<void> {
+    const folderAccessToastId = 'folder-access';
+    if (!window.isSecureContext) {
+      throw new Error('Open Folder requires a secure context (HTTPS or localhost).');
+    }
+    if (
+      typeof window.showDirectoryPicker !== 'function' ||
+      typeof window.showOpenFilePicker !== 'function'
+    ) {
+      throw new Error('This browser context does not support the File System Access API.');
+    }
+    let directoryHandle: DirectoryHandle;
+    try {
+      directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
+    } catch (err: any) {
+      if (err?.name === 'AbortError') return;
+      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
+      throw err;
+    }
+
+    toast.loading('Please select the AsyncAPI file within the folder...', { id: folderAccessToastId });
+    let fileHandle: FileHandle;
+    try {
+      const [handle] = await window.showOpenFilePicker({
+        types: [{ description: 'AsyncAPI files', accept: { 'text/*': ['.yaml', '.yml', '.json'] } }],
+        multiple: false,
+      });
+      fileHandle = handle;
+    } catch (err: any) {
+      toast.dismiss(folderAccessToastId);
+      if (err?.name === 'AbortError') return;
+      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
+      throw err;
+    }
+
+    const pathParts = await directoryHandle.resolve(fileHandle);
+    if (!pathParts) {
+      toast.dismiss(folderAccessToastId);
+      toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
+      return;
+    }
+
+    const localPath = pathParts.join('/');
+    const files = await this.collectLocalProjectFiles(directoryHandle);
+    const selectedFile = await fileHandle.getFile();
+    const selectedContent = await selectedFile.text();
+    const selectedLanguage = this.inferLanguageFromUri(localPath, selectedContent);
+
+    files[localPath] = {
+      uri: localPath,
+      name: this.getFileNameFromUri(localPath),
+      content: selectedContent,
+      language: selectedLanguage,
+      from: 'file',
+      source: `${directoryHandle.name}/${localPath}`,
+      directoryHandle,
+      fileHandle,
+      localPath,
+      modified: false,
+      isAsyncApiDocument: this.isAsyncApiContent(selectedContent),
+      stat: { mtime: Date.now() },
+    };
+
+    filesState.getState().setProjectFiles(files, {
+      activeFileUri: localPath,
+      fileTreeMode: 'local',
+      projectRoot: directoryHandle.name,
+    });
+
     this.updateState({
       content: selectedContent,
       updateModel: true,
@@ -319,432 +323,400 @@ export class EditorService extends AbstractService {
     });
 
     toast.dismiss(folderAccessToastId);
-    toast.success('Folder access granted! File references will now be resolved.');
   }
-  async importFromURL(url: string): Promise<void> {
-    if (!url) {
-      throw new Error('URL is required');
+  async importFromURL(url: string): Promise<void> {
+    if (!url) {
+      throw new Error('URL is required');
+    }
+
+    console.log('[DEBUG:editor] importFromURL', url);
+
+    const currentUrl = window.location.href.split('?')[0];
+    window.history.pushState({}, '', `${currentUrl}?url=${url}`);
+
+    return fetch(url)
+      .then(res => res.text())
+      .then(async text => {
+        const language = this.inferLanguageFromUri(url, text);
+        const projectRoot = (() => {
+          try {
+            return new URL(url).host;
+          } catch {
+            return 'Remote Files';
+          }
+        })();
+
+        const mainFile: File = {
+          uri: url,
+          name: this.getFileNameFromUri(url),
+          content: text,
+          from: 'url',
+          source: url,
+          language,
+          modified: false,
+          isAsyncApiDocument: this.isAsyncApiContent(text),
+          stat: { mtime: Date.now() },
+        };
+
+        filesState.getState().setProjectFiles(
+          { [url]: mainFile },
+          { activeFileUri: url, fileTreeMode: 'remote', projectRoot },
+        );
+
+        this.updateState({
+          content: text,
+          updateModel: true,
+          sendToServer: false,
+          file: mainFile,
+        });
+      })
+      .catch(err => {
+        console.error(err);
+        throw err;
+      });
+  }
+  async importFile(files: FileList | null) {
+    if (files === null || files?.length !== 1) {
+      return;
+    }
+    const file = files.item(0);
+    if (!file) {
+      return;
+    }
+
+    const allowedExtensions = ['json', 'yaml', 'yml', 'avsc'];
+    const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
+    if (!allowedExtensions.includes(ext)) {
+      throw new Error('Invalid file type. Only .json, .yaml, .yml, and .avsc files are supported.');
+    }
+
+    console.log('[DEBUG:editor] importFile', file.name);
+
+    const fileReader = new FileReader();
+    fileReader.onload = fileLoadedEvent => {
+      const content = String(fileLoadedEvent.target?.result || '');
+      const uri = file.name;
+      const language = this.inferLanguageFromUri(uri, content);
+      const importedFile: File = {
+        uri,
+        name: file.name,
+        content,
+        from: 'file',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(content),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
+      this.updateState({
+        content,
+        updateModel: true,
+        sendToServer: false,
+        file: importedFile,
+      });
+    };
+    fileReader.readAsText(file, 'UTF-8');
+  }
+  async importBase64(content: string) {
+    try {
+      const decoded = this.svcs.formatSvc.decodeBase64(content);
+      const uri = 'base64://document';
+      const language = this.inferLanguageFromUri(uri, String(decoded));
+      const importedFile: File = {
+        uri,
+        name: 'Base64 document',
+        content: String(decoded),
+        from: 'base64',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(String(decoded)),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
+      this.updateState({
+        content: String(decoded),
+        updateModel: true,
+        sendToServer: false,
+        file: importedFile,
+      });
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
+  async importFromShareID(shareID: string) {
+    try {
+      const response = await fetch(`/share/${shareID}`);
+      if (!response.ok) {
+        throw new Error('Failed to fetch shared document');
+      }
+
+      const data = await response.json();
+      const uri = `share://${shareID}`;
+      const language = this.inferLanguageFromUri(uri, data.content);
+      const importedFile: File = {
+        uri,
+        name: `Shared ${shareID}`,
+        content: data.content,
+        from: 'share',
+        source: undefined,
+        language,
+        modified: false,
+        isAsyncApiDocument: this.isAsyncApiContent(data.content),
+        stat: { mtime: Date.now() },
+      };
+
+      filesState.getState().setProjectFiles(
+        { [uri]: importedFile },
+        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
+      );
+
+      this.updateState({
+        content: data.content,
+        updateModel: true,
+        sendToServer: false,
+        file: importedFile,
+      });
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
+  async exportAsURL() {
+    try {
+      const file = filesState.getState().files['asyncapi'];
+      const shareID = await fetch('/share', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ content: file.content }),
+      }).then(res => res.text());
+      return `${window.location.origin}/?share=${shareID}`;
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
+
+  async exportAsBase64() {
+    try {
+      const file = filesState.getState().files['asyncapi'];
+      return this.svcs.formatSvc.encodeBase64(file.content);
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
+
+  async convertToYaml() {
+    try {
+      const yamlContent = this.svcs.formatSvc.convertToYaml(this.value);
+      if (yamlContent) {
+        this.updateState({ 
+          content: yamlContent, 
+          updateModel: true, 
+          file: {
+            language: 'yaml',
+          }
+        });
+      }
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
+
+  async convertToJSON() {
+    try {
+      const jsonContent = this.svcs.formatSvc.convertToJSON(this.value);
+      if (jsonContent) {
+        this.updateState({ 
+          content: jsonContent, 
+          updateModel: true, 
+          file: {
+            language: 'json',
+          }
+        });
+      }
+    } catch (err) {
+      console.error(err);
+      throw err;
+    }
+  }
  private getCurrentContentByLanguage() {
+    const currentFile = filesState.getState().files['asyncapi'];
+    if (!currentFile) {
+      throw new Error('No active file to save.');
     }
 
-    console.log('[DEBUG:editor] importFromURL', url);
-
-    const currentUrl = window.location.href.split('?')[0];
-    window.history.pushState({}, '', `${currentUrl}?url=${url}`);
-
-    return fetch(url)
-      .then(res => res.text())
-      .then(async text => {
-        const language = this.inferLanguageFromUri(url, text);
-        const projectRoot = (() => {
-          try {
-            return new URL(url).host;
-          } catch {
-            return 'Remote Files';
-          }
-        })();
-
-        const mainFile: File = {
-          uri: url,
-          name: this.getFileNameFromUri(url),
-          content: text,
-          from: 'url',
-          source: url,
-          language,
-          modified: false,
-          isAsyncApiDocument: this.isAsyncApiContent(text),
-          stat: { mtime: Date.now() },
-        };
-
-        filesState.getState().setProjectFiles(
-          { [url]: mainFile },
-          { activeFileUri: url, fileTreeMode: 'remote', projectRoot },
-        );
-
-        this.updateState({
-          content: text,
-          updateModel: true,
-          sendToServer: false,
-          file: mainFile,
-        });
-      })
-      .catch(err => {
-        console.error(err);
-        throw err;
-      });
-  }
-  async importFile(files: FileList | null) {
-    if (files === null || files?.length !== 1) {
-      return;
+    const language = currentFile.language;
+    const editorContent = this.editor?.getModel()?.getValue();
+    const isValidContent = (value: unknown): value is string =>
+      typeof value === 'string' && value !== 'undefined';
+    let content: string | null = null;
+    if (isValidContent(editorContent)) {
+      content = editorContent;
+    } else if (isValidContent(currentFile.content)) {
+      content = currentFile.content;
     }
-    const file = files.item(0);
-    if (!file) {
-      return;
+    if (!isValidContent(content)) {
+      throw new Error('Failed to get current document content for saving.');
     }
 
-    const allowedExtensions = ['json', 'yaml', 'yml', 'avsc'];
-    const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
-    if (!allowedExtensions.includes(ext)) {
-      throw new Error('Invalid file type. Only .json, .yaml, .yml, and .avsc files are supported.');
-    }
-
-    console.log('[DEBUG:editor] importFile', file.name);
-
-    const fileReader = new FileReader();
-    fileReader.onload = fileLoadedEvent => {
-      const content = String(fileLoadedEvent.target?.result || '');
-      const uri = file.name;
-      const language = this.inferLanguageFromUri(uri, content);
-      const importedFile: File = {
-        uri,
-        name: file.name,
-        content,
-        from: 'file',
-        source: undefined,
-        language,
-        modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(content),
-        stat: { mtime: Date.now() },
-      };
-
-      filesState.getState().setProjectFiles(
-        { [uri]: importedFile },
-        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
-      );
-
-      this.updateState({
-        content,
-        updateModel: true,
-        sendToServer: false,
-        file: importedFile,
-      });
+    return {
+      file: currentFile,
+      language,
+      content,
+      extension: language === 'yaml' ? 'yaml' : 'json',
+      mimeType: language === 'yaml' ? 'text/yaml' : 'application/json',
     };
-    fileReader.readAsText(file, 'UTF-8');
   }
-  async importBase64(content: string) {
-    try {
-      const decoded = this.svcs.formatSvc.decodeBase64(content);
-      const uri = 'base64://document';
-      const language = this.inferLanguageFromUri(uri, String(decoded));
-      const importedFile: File = {
-        uri,
-        name: 'Base64 document',
-        content: String(decoded),
-        from: 'base64',
-        source: undefined,
-        language,
-        modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(String(decoded)),
-        stat: { mtime: Date.now() },
-      };
 
-      filesState.getState().setProjectFiles(
-        { [uri]: importedFile },
-        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
-      );
-
-      this.updateState({
-        content: String(decoded),
-        updateModel: true,
-        sendToServer: false,
-        file: importedFile,
-      });
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-  async importFromShareID(shareID: string) {
-    try {
-      const response = await fetch(`/share/${shareID}`);
-      if (!response.ok) {
-        throw new Error('Failed to fetch shared document');
-      }
+  async saveCurrentFile() {
+    const { file, language, content, extension, mimeType } = this.getCurrentContentByLanguage();
 
-      const data = await response.json();
-      const uri = `share://${shareID}`;
-      const language = this.inferLanguageFromUri(uri, data.content);
-      const importedFile: File = {
-        uri,
-        name: `Shared ${shareID}`,
-        content: data.content,
-        from: 'share',
-        source: undefined,
+    if (file.from === 'file' && file.fileHandle) {
+      const writable = await file.fileHandle.createWritable();
+      await writable.write(content);
+      await writable.close();
+      filesState.getState().updateFile('asyncapi', {
+        content,
         language,
         modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(data.content),
         stat: { mtime: Date.now() },
-      };
-
-      filesState.getState().setProjectFiles(
-        { [uri]: importedFile },
-        { activeFileUri: uri, fileTreeMode: 'none', projectRoot: undefined },
-      );
-
-      this.updateState({
-        content: data.content,
-        updateModel: true,
-        sendToServer: false,
-        file: importedFile,
       });
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-  async exportAsURL() {
-    try {
-      const file = filesState.getState().files['asyncapi'];
-      const shareID = await fetch('/share', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ content: file.content }),
-      }).then(res => res.text());
-      return `${window.location.origin}/?share=${shareID}`;
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-
-  async exportAsBase64() {
-    try {
-      const file = filesState.getState().files['asyncapi'];
-      return this.svcs.formatSvc.encodeBase64(file.content);
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-
-  async convertToYaml() {
-    try {
-      const yamlContent = this.svcs.formatSvc.convertToYaml(this.value);
-      if (yamlContent) {
-        this.updateState({ 
-          content: yamlContent, 
-          updateModel: true, 
-          file: {
-            language: 'yaml',
-          }
-        });
-      }
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-
-  async convertToJSON() {
-    try {
-      const jsonContent = this.svcs.formatSvc.convertToJSON(this.value);
-      if (jsonContent) {
-        this.updateState({ 
-          content: jsonContent, 
-          updateModel: true, 
-          file: {
-            language: 'json',
-          }
-        });
-      }
-    } catch (err) {
-      console.error(err);
-      throw err;
-    }
-  }
-
-  async saveAsYaml() {
-    try {
-      const yamlContent = this.svcs.formatSvc.convertToYaml(this.value);
-      if (yamlContent) {
-        this.downloadFile(yamlContent, `${this.fileName}.yaml`);
-      }
-    } catch (err) {
-      console.error(err);
-      throw err;
+      return;
     }
-  }
 
-  async saveAsJSON() {
-    try {
-      const jsonContent = this.svcs.formatSvc.convertToJSON(this.value);
-      if (jsonContent) {
-        this.downloadFile(jsonContent, `${this.fileName}.json`);
-      }
-    } catch (err) {
-      console.error(err);
-      throw err;
+    if (typeof window.showSaveFilePicker !== 'function') {
+      throw new Error('This browser does not support saving files through Save As dialog.');
     }
-  }
 
-  saveToLocalStorage(editorValue?: string, notify = true) {
-    editorValue = editorValue || this.value;
-
-    // Get current source URL to preserve it
-    const currentFile = filesState.getState().files['asyncapi'];
-    const source = currentFile?.source;
-
-    // Store both content and source in localStorage
-    const documentData = {
-      content: editorValue,
-      source: source || undefined,
-    };
-    localStorage.setItem('document', JSON.stringify(documentData));
-
-    const { updateFile } = filesState.getState();
-    updateFile('asyncapi', {
-      source, // Preserve the source URL
-      modified: false,
+    const suggestedFileName = file.name?.includes('.')
+      ? file.name
+      : `${file.name || 'asyncapi'}.${extension}`;
+    const fileHandle = await window.showSaveFilePicker({
+      suggestedName: suggestedFileName,
+      types: [
+        {
+          description: language === 'yaml' ? 'YAML file' : 'JSON file',
+          accept: { [mimeType]: [`.${extension}`] },
+        },
+      ],
     });
+    const writable = await fileHandle.createWritable();
+    await writable.write(content);
+    await writable.close();
 
-    if (notify) {
-      if (settingsState.getState().editor.autoSaving) {
-        toast.success(
-          <div>
-            <span className="block text-bold">
-              Studio is currently saving your work automatically 💪
-            </span>
-          </div>,
-        );
-      } else {
-        toast.success(
-          <div>
-            <span className="block text-bold">
-              Document succesfully saved to the local storage!
-            </span>
-          </div>,
-        );
-      }
-    }
-  }
-
-  getFromLocalStorage() {
-    const stored = localStorage.getItem('document');
-    if (!stored) return null;
-
-    try {
-      // Try to parse as JSON (new format)
-      const parsed = JSON.parse(stored);
-      if (parsed && typeof parsed === 'object' && 'content' in parsed) {
-        return parsed.content; // Return just the content for compatibility
-      }
-    } catch {
-      // If parsing fails, it's the old format (plain string)
-      return stored;
-    }
-
-    // Fallback to treating as plain string
-    return stored;
-  }
-
-  getSourceFromLocalStorage() {
-    const stored = localStorage.getItem('document');
-    if (!stored) return undefined;
-
-    try {
-      // Try to parse as JSON (new format)
-      const parsed = JSON.parse(stored);
-      if (parsed && typeof parsed === 'object' && 'source' in parsed) {
-        return parsed.source;
-      }
-    } catch {
-      // If parsing fails, it's the old format (no source)
-      return undefined;
-    }
-
-    return undefined;
-  }
-
-  private applyMarkersAndDecorations(diagnostics: Diagnostic[] = []) {
-    const editor = this.editor;
-    const model = editor?.getModel();
-    const monaco = this.svcs.monacoSvc.monaco;
-
-    if (!editor || !model || !monaco) {
-      return;
-    }
-
-    const { markers, decorations } = this.createMarkersAndDecorations(diagnostics);
-    monaco.editor.setModelMarkers(model, 'asyncapi', markers);
-    let oldDecorations = this.decorations.get('asyncapi') || [];
-    oldDecorations = editor.deltaDecorations(oldDecorations, decorations);
-    this.decorations.set('asyncapi', oldDecorations);
-  }
-
-  createMarkersAndDecorations(diagnostics: Diagnostic[] = []) {
-    const newDecorations: monacoAPI.editor.IModelDecoration[] = [];
-    const newMarkers: monacoAPI.editor.IMarkerData[] = [];
-
-    diagnostics.forEach(diagnostic => {
-      const { message, range, severity } = diagnostic;
-
-      if (severity !== DiagnosticSeverity.Error) {
-        newDecorations.push({
-          id: 'asyncapi',
-          ownerId: 0,
-          range: new Range(
-            range.start.line + 1, 
-            range.start.character + 1,
-            range.end.line + 1,
-            range.end.character + 1
-          ),
-          options: {
-            glyphMarginClassName: this.getSeverityClassName(severity),
-            glyphMarginHoverMessage: { value: message },
-          },
-        });
-        return;
-      }
-  
-      newMarkers.push({
-        startLineNumber: range.start.line + 1,
-        startColumn: range.start.character + 1,
-        endLineNumber: range.end.line + 1,
-        endColumn: range.end.character + 1,
-        severity: this.getSeverity(severity),
-        message,
-      });
+    filesState.getState().updateFile('asyncapi', {
+      content,
+      language,
+      name: fileHandle.name || suggestedFileName,
+      from: 'file',
+      source: undefined,
+      fileHandle,
+      directoryHandle: undefined,
+      localPath: undefined,
+      modified: false,
+      stat: { mtime: Date.now() },
     });
-
-    return { decorations: newDecorations, markers: newMarkers };
-  }
-
-  private getSeverity(severity: DiagnosticSeverity): monacoAPI.MarkerSeverity {
-    switch (severity) {
-    case DiagnosticSeverity.Error: return MarkerSeverity.Error;
-    case DiagnosticSeverity.Warning: return MarkerSeverity.Warning;
-    case DiagnosticSeverity.Information: return MarkerSeverity.Info;
-    case DiagnosticSeverity.Hint: return MarkerSeverity.Hint;
-    default: return MarkerSeverity.Error;
-    }
-  }
-
-  private getSeverityClassName(severity: DiagnosticSeverity): string {
-    switch (severity) {
-    case DiagnosticSeverity.Warning: return 'diagnostic-warning';
-    case DiagnosticSeverity.Information: return 'diagnostic-information';
-    case DiagnosticSeverity.Hint: return 'diagnostic-hint';
-    default: return 'diagnostic-warning';
-    }
-  }
-
-  private fileName = 'asyncapi';
-  private downloadFile(content: string, fileName: string) {
-    return fileDownload(content, fileName);
-  }
-
+  }
+
+  private applyMarkersAndDecorations(diagnostics: Diagnostic[] = []) {
+    const editor = this.editor;
+    const model = editor?.getModel();
+    const monaco = this.svcs.monacoSvc.monaco;
+
+    if (!editor || !model || !monaco) {
+      return;
+    }
+
+    const { markers, decorations } = this.createMarkersAndDecorations(diagnostics);
+    monaco.editor.setModelMarkers(model, 'asyncapi', markers);
+    let oldDecorations = this.decorations.get('asyncapi') || [];
+    oldDecorations = editor.deltaDecorations(oldDecorations, decorations);
+    this.decorations.set('asyncapi', oldDecorations);
+  }
+
+  createMarkersAndDecorations(diagnostics: Diagnostic[] = []) {
+    const newDecorations: monacoAPI.editor.IModelDecoration[] = [];
+    const newMarkers: monacoAPI.editor.IMarkerData[] = [];
+
+    diagnostics.forEach(diagnostic => {
+      const { message, range, severity } = diagnostic;
+
+      if (severity !== DiagnosticSeverity.Error) {
+        newDecorations.push({
+          id: 'asyncapi',
+          ownerId: 0,
+          range: new Range(
+            range.start.line + 1, 
+            range.start.character + 1,
+            range.end.line + 1,
+            range.end.character + 1
+          ),
+          options: {
+            glyphMarginClassName: this.getSeverityClassName(severity),
+            glyphMarginHoverMessage: { value: message },
+          },
+        });
+        return;
+      }
+  
+      newMarkers.push({
+        startLineNumber: range.start.line + 1,
+        startColumn: range.start.character + 1,
+        endLineNumber: range.end.line + 1,
+        endColumn: range.end.character + 1,
+        severity: this.getSeverity(severity),
+        message,
+      });
+    });
+
+    return { decorations: newDecorations, markers: newMarkers };
+  }
+
+  private getSeverity(severity: DiagnosticSeverity): monacoAPI.MarkerSeverity {
+    switch (severity) {
+    case DiagnosticSeverity.Error: return MarkerSeverity.Error;
+    case DiagnosticSeverity.Warning: return MarkerSeverity.Warning;
+    case DiagnosticSeverity.Information: return MarkerSeverity.Info;
+    case DiagnosticSeverity.Hint: return MarkerSeverity.Hint;
+    default: return MarkerSeverity.Error;
+    }
+  }
+
+  private getSeverityClassName(severity: DiagnosticSeverity): string {
+    switch (severity) {
+    case DiagnosticSeverity.Warning: return 'diagnostic-warning';
+    case DiagnosticSeverity.Information: return 'diagnostic-information';
+    case DiagnosticSeverity.Hint: return 'diagnostic-hint';
+    default: return 'diagnostic-warning';
+    }
+  }
   private subcribeToDocuments() {
-    documentsState.subscribe((state, prevState) => {
-      const newDocuments = state.documents;
-      const oldDocuments = prevState.documents;
-
-      Object.entries(newDocuments).forEach(([uri, document]) => {
-        const oldDocument = oldDocuments[String(uri)];
-        if (document === oldDocument) return;
-        this.applyMarkersAndDecorations(document.diagnostics.filtered);
-      });
-    });
-  }
+    documentsState.subscribe((state, prevState) => {
+      const newDocuments = state.documents;
+      const oldDocuments = prevState.documents;
+
+      Object.entries(newDocuments).forEach(([uri, document]) => {
+        const oldDocument = oldDocuments[String(uri)];
+        if (document === oldDocument) return;
+        this.applyMarkersAndDecorations(document.diagnostics.filtered);
+      });
+    });
+  }
 }
-
+
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index 20e84dd36..dac38de5f 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -252,7 +252,7 @@ export class ParserService extends AbstractService {
           diagnostic.message.includes('File references are not yet supported'))
       ) {
         diagnostic.message =
-          'Local file reference detected. Click Import → Grant Folder Access to resolve this reference.';
+          'Local file reference detected.  Open this file using "Open Folder" to grant folder access and resolve relative references.';
       }
     });
     
diff --git a/apps/studio/src/state/settings.state.ts b/apps/studio/src/state/settings.state.ts
index 1b4fbd10b..371e14aba 100644
--- a/apps/studio/src/state/settings.state.ts
+++ b/apps/studio/src/state/settings.state.ts
@@ -2,10 +2,6 @@ import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
 
 export type SettingsState = {
-  editor: {
-    autoSaving: boolean;
-    savingDelay: number;
-  };
   governance: {
     show: {
       warnings: boolean;
@@ -21,10 +17,6 @@ export type SettingsState = {
 export const settingsState = create(
   persist<SettingsState>(() => 
     ({
-      editor: {
-        autoSaving: true,
-        savingDelay: 625,
-      },
       governance: {
         show: {
           warnings: true,
@@ -43,4 +35,4 @@ export const settingsState = create(
   ),
 );
 
-export const useSettingsState = settingsState;
\ No newline at end of file
+export const useSettingsState = settingsState;
diff --git a/apps/studio/src/types/window-file-system-access.d.ts b/apps/studio/src/types/window-file-system-access.d.ts
index 11a76f628..5fd2e694b 100644
--- a/apps/studio/src/types/window-file-system-access.d.ts
+++ b/apps/studio/src/types/window-file-system-access.d.ts
@@ -5,5 +5,6 @@ declare global {
   interface Window {
     showDirectoryPicker: (options?: { mode?: 'read' | 'readwrite' }) => Promise<FileSystemDirectoryHandle>;
     showOpenFilePicker: (options?: unknown) => Promise<FileSystemFileHandle[]>;
+    showSaveFilePicker: (options?: unknown) => Promise<FileSystemFileHandle>;
   }
 }

From 3bfc88aa0ad5af8c77910e8c8da693e5b16b7604 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 07:38:21 +0100
Subject: [PATCH 17/23] add markdown and avsc preview

---
 apps/studio/package.json                      |   1 +
 apps/studio/src/components/Content.tsx        |   2 +
 .../src/components/Editor/EditorSidebar.tsx   |   2 +-
 .../src/components/Editor/MonacoWrapper.tsx   |   1 +
 apps/studio/src/components/FileTreeView.tsx   |   6 +-
 .../src/components/Modals/RedirectedModal.tsx |   2 +-
 apps/studio/src/components/Navigation.tsx     |   7 +-
 apps/studio/src/components/Navigationv3.tsx   |   7 +-
 apps/studio/src/components/Sidebar.tsx        |  13 +-
 .../src/components/Template/AvroPreview.tsx   |  19 +
 .../src/components/Template/HTMLWrapper.tsx   |  16 +-
 .../components/Template/MarkdownPreview.tsx   | 135 ++++
 .../src/components/Template/Template.tsx      |  19 +-
 .../src/components/Template/avro-diagram.ts   | 528 ++++++++++++++++
 apps/studio/src/components/Template/index.ts  |   1 +
 apps/studio/src/schemas/avro/avro-schema.json | 290 +++++++++
 apps/studio/src/services/app.service.ts       |  11 +-
 apps/studio/src/services/editor.service.tsx   | 179 +++---
 apps/studio/src/services/format.service.ts    |  30 +
 apps/studio/src/services/monaco.service.ts    |  81 ++-
 .../studio/src/services/navigation.service.ts |   9 +-
 apps/studio/src/services/parser.service.ts    |  31 +-
 apps/studio/src/state/files.state.ts          |   2 +-
 apps/studio/src/state/panels.state.ts         |   2 +-
 pnpm-lock.yaml                                | 576 ++++++++++++++++++
 25 files changed, 1855 insertions(+), 115 deletions(-)
 create mode 100644 apps/studio/src/components/Template/AvroPreview.tsx
 create mode 100644 apps/studio/src/components/Template/MarkdownPreview.tsx
 create mode 100644 apps/studio/src/components/Template/avro-diagram.ts
 create mode 100644 apps/studio/src/schemas/avro/avro-schema.json

diff --git a/apps/studio/package.json b/apps/studio/package.json
index dfc18d298..2ada6435c 100644
--- a/apps/studio/package.json
+++ b/apps/studio/package.json
@@ -86,6 +86,7 @@
     "js-yaml": "^4.1.1",
     "monaco-editor": "0.34.1",
     "monaco-yaml": "4.0.2",
+    "mermaid": "^11.13.0",
     "next": "14.2.35",
     "postcss": "8.4.31",
     "react": "18.2.0",
diff --git a/apps/studio/src/components/Content.tsx b/apps/studio/src/components/Content.tsx
index 8a61b3d79..1db21e8f9 100644
--- a/apps/studio/src/components/Content.tsx
+++ b/apps/studio/src/components/Content.tsx
@@ -3,6 +3,7 @@ import { Editor } from './Editor/Editor';
 import { Navigation } from './Navigation';
 import { Navigationv3 } from './Navigationv3';
 import { Template } from './Template';
+import { AvroPreview } from './Template/AvroPreview';
 import { VisualiserTemplate } from './Visualiser';
 
 import { debounce } from '@/helpers';
@@ -70,6 +71,7 @@ export const Content: FunctionComponent<ContentProps> = () => { // eslint-disabl
         >
           {navigationAndEditor}
           {viewType === 'template' && <Template />}
+          {viewType === 'avro' && <AvroPreview />}
           {viewType === 'visualiser' && <VisualiserTemplate />}
         </SplitPane> 
       </div>
diff --git a/apps/studio/src/components/Editor/EditorSidebar.tsx b/apps/studio/src/components/Editor/EditorSidebar.tsx
index cecd7f004..ca4e82bd8 100644
--- a/apps/studio/src/components/Editor/EditorSidebar.tsx
+++ b/apps/studio/src/components/Editor/EditorSidebar.tsx
@@ -19,7 +19,7 @@ export const EditorSidebar: React.FunctionComponent<
     documentFromText = 'From localStorage';
   } else if (from === 'file') {
     const path = source || localPath || uri;
-    documentFromText = path ? `From local file ${path}` : 'From local file';
+    documentFromText = path ? `From local folder: ${path}` : 'From local folder';
   } else if (from === 'url') {
     documentFromText = `From URL ${source || uri || ''}`.trim();
   } else if (from === 'base64') {
diff --git a/apps/studio/src/components/Editor/MonacoWrapper.tsx b/apps/studio/src/components/Editor/MonacoWrapper.tsx
index 4c0cf1e3c..b9c9af311 100644
--- a/apps/studio/src/components/Editor/MonacoWrapper.tsx
+++ b/apps/studio/src/components/Editor/MonacoWrapper.tsx
@@ -31,6 +31,7 @@ export const MonacoWrapper: FunctionComponent<MonacoEditorProps> = ({
   return (
     <MonacoEditor
       key={file.uri}
+      path={file.uri}
       language={file.language}
       value={file.content}
       theme="asyncapi-theme"
diff --git a/apps/studio/src/components/FileTreeView.tsx b/apps/studio/src/components/FileTreeView.tsx
index 9fa5fff49..4f086db67 100644
--- a/apps/studio/src/components/FileTreeView.tsx
+++ b/apps/studio/src/components/FileTreeView.tsx
@@ -74,6 +74,7 @@ function getFileTypeColor(name: string): string {
   if (lower.endsWith('.yaml') || lower.endsWith('.yml')) return 'text-blue-400';
   if (lower.endsWith('.json')) return 'text-yellow-400';
   if (lower.endsWith('.avsc')) return 'text-green-400';
+  if (lower.endsWith('.md') || lower.endsWith('.markdown')) return 'text-purple-400';
   return 'text-gray-300';
 }
 
@@ -260,7 +261,7 @@ export const FileTreeView: React.FC = () => {
     <div className="mb-4 border border-gray-700 bg-gray-800 rounded">
       <button
         type="button"
-        className="w-full flex items-center justify-between px-2 py-2 text-left text-white text-sm border-b border-gray-700"
+        className="w-full flex items-center justify-between px-2 py-2 text-left text-white text-base border-b border-gray-700"
         onClick={() => setCollapsed((prev) => !prev)}
       >
         <span>
@@ -274,9 +275,6 @@ export const FileTreeView: React.FC = () => {
           {projectFiles.length === 0 && <div className="px-2 py-3 text-xs text-gray-400">No project files available.</div>}
           {projectFiles.length > 0 && <div className="py-1">{treeNodes.map((node) => renderNode(node))}</div>}
           {fileTreeLoading && <div className="px-2 py-2 text-xs text-gray-400">Loading file...</div>}
-          {activeFile && activeFile.isAsyncApiDocument === false && (
-            <div className="px-2 py-2 text-xs text-gray-400 border-t border-gray-700">Referenced file (not an AsyncAPI document)</div>
-          )}
         </div>
       )}
     </div>
diff --git a/apps/studio/src/components/Modals/RedirectedModal.tsx b/apps/studio/src/components/Modals/RedirectedModal.tsx
index 6846d09a4..aa884df39 100644
--- a/apps/studio/src/components/Modals/RedirectedModal.tsx
+++ b/apps/studio/src/components/Modals/RedirectedModal.tsx
@@ -7,7 +7,7 @@ import { Markdown } from '../common';
 const CHANGES = `
 Below are the changes compared to the old AsyncAPI Playground:
   
-- There is no preview for markdown.
+- Markdown files now have preview support, including Mermaid code blocks.
 - Studio supports the same query parameters except **template**.
 - To download an AsyncAPI document from an external source use the editor menu and select **Import from URL**. There is also an option to use a local file, base64 saved file, convert a given version of AsyncAPI document to a newer one as well as change the format from YAML to JSON and vice versa. There is also option to download AsyncAPI document as file.
 - To generate the template, please click on the **Generate code/docs** item in the menu at the top right corner of the editor, enter (needed) the parameters and click **Generate**.
diff --git a/apps/studio/src/components/Navigation.tsx b/apps/studio/src/components/Navigation.tsx
index 8ceb9a292..7906938a0 100644
--- a/apps/studio/src/components/Navigation.tsx
+++ b/apps/studio/src/components/Navigation.tsx
@@ -315,9 +315,12 @@ export const Navigation: React.FunctionComponent<NavigationProps> = ({
   const [hash, setHash] = useState(window.location.hash);
   const [loading, setloading] = useState(false);
 
-  const { navigationSvc } = useServices();
+  const { navigationSvc, formatSvc } = useServices();
   const rawSpec = useFilesState(state => state.files['asyncapi']?.content);
   const document = useDocumentsState(state => state.documents['asyncapi']?.document);
+  const emptyStateMessage = formatSvc.detectSpecType(rawSpec || '') === 'openapi'
+    ? 'OpenAPI document detected. AsyncAPI navigation is not available for this file.'
+    : 'Empty or invalid document. Please fix errors/define AsyncAPI document.';
 
   useEffect(() => {
     const fn = () => {
@@ -350,7 +353,7 @@ export const Navigation: React.FunctionComponent<NavigationProps> = ({
           {loading ?(
             <div className="rotating-wheel"></div>
           ) : (
-            <p className='text-white'>Empty or invalid document. Please fix errors/define AsyncAPI document.</p>
+            <p className='text-white'>{emptyStateMessage}</p>
           )
           }
         </div>
diff --git a/apps/studio/src/components/Navigationv3.tsx b/apps/studio/src/components/Navigationv3.tsx
index 40c923465..b1270ea21 100644
--- a/apps/studio/src/components/Navigationv3.tsx
+++ b/apps/studio/src/components/Navigationv3.tsx
@@ -380,9 +380,12 @@ export const Navigationv3: React.FunctionComponent<NavigationProps> = ({
 }) => {
   const [hash, setHash] = useState(window.location.hash);
 
-  const { navigationSvc } = useServices();
+  const { navigationSvc, formatSvc } = useServices();
   const rawSpec = useFilesState(state => state.files['asyncapi']?.content);
   const document = useDocumentsState(state => state.documents['asyncapi']?.document);
+  const emptyStateMessage = formatSvc.detectSpecType(rawSpec || '') === 'openapi'
+    ? 'OpenAPI document detected. AsyncAPI navigation is not available for this file.'
+    : 'Empty or invalid document. Please fix errors/define AsyncAPI document.';
 
   useEffect(() => {
     const fn = () => {
@@ -402,7 +405,7 @@ export const Navigationv3: React.FunctionComponent<NavigationProps> = ({
       <div className={`flex flex-none flex-col overflow-y-auto overflow-x-hidden bg-gray-800 h-full ${className}`} id="navigation-panel">
         <FileTreeView />
         <div className="flex overflow-hidden bg-gray-800 h-full justify-center items-center text-center text-white text-md px-6">
-          Empty or invalid document. Please fix errors/define AsyncAPI document.
+          {emptyStateMessage}
         </div>
       </div>
     );
diff --git a/apps/studio/src/components/Sidebar.tsx b/apps/studio/src/components/Sidebar.tsx
index f1095a2ce..876a95bb4 100644
--- a/apps/studio/src/components/Sidebar.tsx
+++ b/apps/studio/src/components/Sidebar.tsx
@@ -15,7 +15,7 @@ function updateState(panelName: keyof PanelsState['show'], type?: PanelsState['s
   let secondaryPanelType = settingsState.secondaryPanelType;
   const newShow = { ...settingsState.show };
 
-  if (type === 'template' || type === 'visualiser') {
+  if (type === 'template' || type === 'visualiser' || type === 'avro') {
     // on current type
     if (secondaryPanelType === type) {
       newShow[`${panelName}`] = !newShow[`${panelName}`];
@@ -95,6 +95,17 @@ export const Sidebar: FunctionComponent<SidebarProps> = () => {
       enabled: true,
       dataTest: 'button-template-preview',
     },
+    // avro preview
+    {
+      name: 'avro',
+      title: 'Avro preview',
+      isActive: show.secondaryPanel && secondaryPanelType === 'avro',
+      onClick: () => updateState('secondaryPanel', 'avro'),
+      icon: <VscGraph className="w-5 h-5" />,
+      tooltip: 'Avro preview',
+      enabled: true,
+      dataTest: 'button-avro-preview',
+    },
     // visuliser
     {
       name: 'visualiser',
diff --git a/apps/studio/src/components/Template/AvroPreview.tsx b/apps/studio/src/components/Template/AvroPreview.tsx
new file mode 100644
index 000000000..3184d6825
--- /dev/null
+++ b/apps/studio/src/components/Template/AvroPreview.tsx
@@ -0,0 +1,19 @@
+import React, { useMemo } from 'react';
+
+import { useFilesState } from '@/state';
+
+import { MarkdownPreview } from './MarkdownPreview';
+import { buildAvroDiagramMarkdown } from './avro-diagram';
+
+export const AvroPreview: React.FunctionComponent = () => {
+  const { file, files } = useFilesState((state) => ({
+    file: state.files['asyncapi'],
+    files: state.files,
+  }));
+
+  const markdown = useMemo(() => {
+    return buildAvroDiagramMarkdown(file, files);
+  }, [file, files]);
+
+  return <MarkdownPreview content={markdown} />;
+};
diff --git a/apps/studio/src/components/Template/HTMLWrapper.tsx b/apps/studio/src/components/Template/HTMLWrapper.tsx
index aead261bd..f26a91943 100644
--- a/apps/studio/src/components/Template/HTMLWrapper.tsx
+++ b/apps/studio/src/components/Template/HTMLWrapper.tsx
@@ -1,8 +1,8 @@
-import React, { useState, useEffect } from 'react';
+import React, { useState, useEffect, useMemo } from 'react';
 import { AsyncApiComponentWP } from '@asyncapi/react-component';
 
 import { useServices } from '../../services';
-import { appState, useDocumentsState, useSettingsState, useOtherState, otherState } from '../../state';
+import { appState, useDocumentsState, useSettingsState, useOtherState, otherState, useFilesState } from '../../state';
 
 import { AsyncAPIDocumentInterface } from '@asyncapi/parser';
 
@@ -10,12 +10,20 @@ interface HTMLWrapperProps {}
 
 export const HTMLWrapper: React.FunctionComponent<HTMLWrapperProps> = () => {
   const [parsedSpec, setParsedSpec] = useState<AsyncAPIDocumentInterface | null>(null);
-  const { navigationSvc } = useServices();
+  const { navigationSvc, formatSvc } = useServices();
   const document = useDocumentsState(state => state.documents['asyncapi']?.document) || null;
+  const activeFile = useFilesState(state => state.files['asyncapi']);
   const [loading, setloading] = useState(false);
 
   const autoRendering = useSettingsState(state => state.templates.autoRendering);
   const templateRerender = useOtherState(state => state.templateRerender);
+  const emptyStateMessage = useMemo(() => {
+    const specType = formatSvc.detectSpecType(activeFile?.content || '');
+    if (specType === 'openapi') {
+      return 'OpenAPI document detected. AsyncAPI preview is not available for this file.';
+    }
+    return 'Empty or invalid document. Please fix errors/define AsyncAPI document.';
+  }, [activeFile?.content, formatSvc]);
 
   useEffect(() => {
     navigationSvc.scrollToHash();
@@ -49,7 +57,7 @@ export const HTMLWrapper: React.FunctionComponent<HTMLWrapperProps> = () => {
         {loading ?(
           <div className="rotating-wheel"></div>
         ) : (
-          <p>Empty or invalid document. Please fix errors/define AsyncAPI document.</p>
+          <p>{emptyStateMessage}</p>
         )
         }
       </div>
diff --git a/apps/studio/src/components/Template/MarkdownPreview.tsx b/apps/studio/src/components/Template/MarkdownPreview.tsx
new file mode 100644
index 000000000..cd3ed28c0
--- /dev/null
+++ b/apps/studio/src/components/Template/MarkdownPreview.tsx
@@ -0,0 +1,135 @@
+import React, { useEffect, useRef } from 'react';
+
+import { Markdown } from '../common';
+
+interface MarkdownPreviewProps {
+  content: string;
+}
+
+let mermaidLoader: Promise<any> | null = null;
+
+function looksLikeMermaidDefinition(codeElement: Element): boolean {
+  const className = (codeElement as HTMLElement).className || '';
+  if (className.includes('mermaid')) {
+    return true;
+  }
+
+  const content = (codeElement.textContent || '').trimStart();
+  if (!content) {
+    return false;
+  }
+
+  return (
+    content.startsWith('classDiagram') ||
+    content.startsWith('graph ') ||
+    content.startsWith('flowchart') ||
+    content.startsWith('sequenceDiagram') ||
+    content.startsWith('erDiagram') ||
+    content.startsWith('stateDiagram') ||
+    content.startsWith('gantt') ||
+    content.startsWith('journey') ||
+    content.startsWith('pie')
+  );
+}
+
+async function loadMermaid() {
+  if (!mermaidLoader) {
+    mermaidLoader = import('mermaid').then((module) => {
+      const mermaid = module.default;
+      mermaid.initialize({
+        startOnLoad: false,
+        securityLevel: 'strict',
+        suppressErrorRendering: true,
+      });
+      return mermaid;
+    });
+  }
+  return mermaidLoader;
+}
+
+async function isValidMermaidDefinition(mermaid: any, definition: string): Promise<boolean> {
+  try {
+    const result = await mermaid.parse(definition, { suppressErrors: true });
+    return result !== false;
+  } catch {
+    return false;
+  }
+}
+
+export const MarkdownPreview: React.FunctionComponent<MarkdownPreviewProps> = ({ content }) => {
+  const previewRef = useRef<HTMLDivElement | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    const renderMermaidBlocks = async () => {
+      const root = previewRef.current;
+      if (!root) {
+        return;
+      }
+
+      const codeBlocks = Array.from(root.querySelectorAll('pre code')).filter((codeElement) =>
+        looksLikeMermaidDefinition(codeElement),
+      );
+      if (codeBlocks.length === 0) {
+        return;
+      }
+
+      try {
+        const mermaid = await loadMermaid();
+        await Promise.all(
+          codeBlocks.map(async (codeElement, index) => {
+            const definition = codeElement.textContent?.trim() || '';
+            if (!definition) {
+              return;
+            }
+
+            const pre = codeElement.closest('pre');
+            if (!pre || cancelled) {
+              return;
+            }
+
+            const isValid = await isValidMermaidDefinition(mermaid, definition);
+            if (!isValid) {
+              return;
+            }
+
+            try {
+              const id = `studio-mermaid-${Date.now()}-${index}`;
+              const { svg, bindFunctions } = await mermaid.render(id, definition);
+              if (cancelled) {
+                return;
+              }
+
+              const wrapper = document.createElement('div');
+              wrapper.className = 'my-4 overflow-x-auto bg-white p-4 rounded';
+              wrapper.innerHTML = svg;
+              bindFunctions?.(wrapper);
+              pre.replaceWith(wrapper);
+            } catch {
+              return;
+            }
+          }),
+        );
+      } catch {
+        return;
+      }
+    };
+
+    renderMermaidBlocks().catch(() => undefined);
+
+    return () => {
+      cancelled = true;
+    };
+  }, [content]);
+
+  return (
+    <div className="flex flex-1 flex-col h-full overflow-hidden">
+      <div ref={previewRef} className="overflow-auto h-full text-gray-900 p-4 bg-white">
+        <Markdown>
+          {content}
+        </Markdown>
+      </div>
+    </div>
+  );
+};
diff --git a/apps/studio/src/components/Template/Template.tsx b/apps/studio/src/components/Template/Template.tsx
index 912a38527..8f8072aa4 100644
--- a/apps/studio/src/components/Template/Template.tsx
+++ b/apps/studio/src/components/Template/Template.tsx
@@ -2,16 +2,33 @@ import React from 'react';
 
 import { TemplateSidebar } from './TemplateSidebar';
 import { HTMLWrapper } from './HTMLWrapper';
+import { MarkdownPreview } from './MarkdownPreview';
+import { AvroPreview } from './AvroPreview';
 
 import { appState } from '../../state';
+import { useFilesState } from '@/state';
 
 interface TemplateProps {}
 
 export const Template: React.FunctionComponent<TemplateProps> = () => {
+  const activeFile = useFilesState((state) => state.files['asyncapi']);
+  const isMarkdownFile = Boolean(
+    activeFile?.language === 'markdown' ||
+    activeFile?.uri?.toLowerCase().endsWith('.md') ||
+    activeFile?.uri?.toLowerCase().endsWith('.markdown'),
+  );
+  const isAvroFile = Boolean(activeFile?.uri?.toLowerCase().endsWith('.avsc'));
+  let previewPanel = <HTMLWrapper />;
+  if (isAvroFile) {
+    previewPanel = <AvroPreview />;
+  } else if (isMarkdownFile) {
+    previewPanel = <MarkdownPreview content={activeFile?.content || ''} />;
+  }
+
   return (
     <div className="flex flex-1 flex-col h-full overflow-hidden">
       {!appState.getState().readOnly && <TemplateSidebar />}
-      <HTMLWrapper />
+      {previewPanel}
     </div>
   );
 };
diff --git a/apps/studio/src/components/Template/avro-diagram.ts b/apps/studio/src/components/Template/avro-diagram.ts
new file mode 100644
index 000000000..c20e36a91
--- /dev/null
+++ b/apps/studio/src/components/Template/avro-diagram.ts
@@ -0,0 +1,528 @@
+import type { File } from '@/state/files.state';
+
+type AvroField = {
+  name: string;
+  typeLabel: string;
+  references: string[];
+  collection: boolean;
+};
+
+type AvroEntity = {
+  fqName: string;
+  displayName: string;
+  namespace?: string;
+  kind: 'record' | 'enum';
+  fields: AvroField[];
+  symbols: string[];
+};
+
+const AVRO_PREVIEW_TITLE = '# Avro Preview';
+
+const AVRO_PRIMITIVES = new Set([
+  'null',
+  'boolean',
+  'int',
+  'long',
+  'float',
+  'double',
+  'bytes',
+  'string',
+]);
+
+function isObject(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function getDirectoryOfUri(uri: string): string {
+  if (!uri) return '';
+  const normalized = uri.replace(/\\/g, '/');
+  const lastSlash = normalized.lastIndexOf('/');
+  return lastSlash >= 0 ? normalized.slice(0, lastSlash) : '';
+}
+
+function getBasename(uri: string): string {
+  const normalized = uri.replace(/\\/g, '/');
+  const lastSlash = normalized.lastIndexOf('/');
+  return lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized;
+}
+
+function isAvroReferenceFile(uri: string): boolean {
+  return uri.toLowerCase().endsWith('.avsc');
+}
+
+function getTypeNameAndNamespace(fqName: string): { typeName: string; namespace?: string } {
+  const idx = fqName.lastIndexOf('.');
+  if (idx < 0) {
+    return { typeName: fqName, namespace: undefined };
+  }
+  return {
+    typeName: fqName.slice(idx + 1),
+    namespace: fqName.slice(0, idx),
+  };
+}
+
+function getQualifiedName(name: string, namespace?: string): string {
+  if (!name) return '';
+  if (name.includes('.')) return name;
+  return namespace ? `${namespace}.${name}` : name;
+}
+
+function getShortName(fqName: string): string {
+  const idx = fqName.lastIndexOf('.');
+  return idx >= 0 ? fqName.slice(idx + 1) : fqName;
+}
+
+function getClassId(fqName: string): string {
+  const normalized = fqName.replace(/[^a-zA-Z0-9_]/g, '_');
+  return normalized || 'UnknownType';
+}
+
+function escapeMermaidLabel(value: string): string {
+  return String(value).replace(/"/g, '\\"');
+}
+
+function analyzeType(
+  typeValue: unknown,
+  namespace: string | undefined,
+  entities: Map<string, AvroEntity>,
+): { label: string; references: string[]; collection: boolean } {
+  if (typeof typeValue === 'string') {
+    if (AVRO_PRIMITIVES.has(typeValue)) {
+      return { label: typeValue, references: [], collection: false };
+    }
+    const fqName = getQualifiedName(typeValue, namespace);
+    return { label: getShortName(fqName), references: [fqName], collection: false };
+  }
+
+  if (Array.isArray(typeValue)) {
+    const analyzed = typeValue
+      .filter((entry) => !(typeof entry === 'string' && entry === 'null'))
+      .map((entry) => analyzeType(entry, namespace, entities));
+    const labels = analyzed.map((entry) => entry.label);
+    const refs = analyzed.flatMap((entry) => entry.references);
+    return {
+      label: labels.length > 0 ? labels.join(' | ') : 'null',
+      references: Array.from(new Set(refs)),
+      collection: false,
+    };
+  }
+
+  if (!isObject(typeValue)) {
+    return { label: 'unknown', references: [], collection: false };
+  }
+
+  const rawType = typeValue.type;
+  if (rawType === 'array') {
+    const items = analyzeType(typeValue.items, namespace, entities);
+    return {
+      label: `${items.label}[]`,
+      references: items.references,
+      collection: true,
+    };
+  }
+
+  if (rawType === 'map') {
+    const values = analyzeType(typeValue.values, namespace, entities);
+    return {
+      label: `map[string, ${values.label}]`,
+      references: values.references,
+      collection: false,
+    };
+  }
+
+  if (rawType === 'record') {
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    const nested = extractRecord(typeValue, namespace, entities);
+    return {
+      label: nested ? getShortName(nested.fqName) : 'record',
+      references: nested ? [nested.fqName] : [],
+      collection: false,
+    };
+  }
+  if (rawType === 'enum') {
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    const nestedEnum = extractEnum(typeValue, namespace, entities);
+    return {
+      label: nestedEnum ? getShortName(nestedEnum.fqName) : 'enum',
+      references: nestedEnum ? [nestedEnum.fqName] : [],
+      collection: false,
+    };
+  }
+
+  if (typeof rawType === 'string') {
+    if (AVRO_PRIMITIVES.has(rawType)) {
+      return { label: rawType, references: [], collection: false };
+    }
+    const fqName = getQualifiedName(rawType, namespace);
+    return { label: getShortName(fqName), references: [fqName], collection: false };
+  }
+
+  if (Array.isArray(rawType)) {
+    return analyzeType(rawType, namespace, entities);
+  }
+
+  return { label: 'unknown', references: [], collection: false };
+}
+
+function extractRecord(
+  schema: unknown,
+  fallbackNamespace: string | undefined,
+  entities: Map<string, AvroEntity>,
+): AvroEntity | undefined {
+  if (!isObject(schema) || schema.type !== 'record' || typeof schema.name !== 'string') {
+    return undefined;
+  }
+
+  const namespace = typeof schema.namespace === 'string' ? schema.namespace : fallbackNamespace;
+  const fqName = getQualifiedName(schema.name, namespace);
+  if (!fqName) {
+    return undefined;
+  }
+
+  const existing = entities.get(fqName);
+  if (existing && existing.kind === 'record' && existing.fields.length > 0) {
+    return existing;
+  }
+
+  const fields: AvroField[] = [];
+  const avroFields = Array.isArray(schema.fields) ? schema.fields : [];
+  for (const field of avroFields) {
+    if (!isObject(field) || typeof field.name !== 'string') {
+      continue;
+    }
+    const analyzed = analyzeType(field.type, namespace, entities);
+    fields.push({
+      name: field.name,
+      typeLabel: analyzed.label,
+      references: analyzed.references,
+      collection: analyzed.collection,
+    });
+  }
+
+  const record: AvroEntity = {
+    fqName,
+    displayName: getShortName(fqName),
+    namespace,
+    kind: 'record',
+    fields,
+    symbols: [],
+  };
+  entities.set(fqName, record);
+  return record;
+}
+
+function extractEnum(
+  schema: unknown,
+  fallbackNamespace: string | undefined,
+  entities: Map<string, AvroEntity>,
+): AvroEntity | undefined {
+  if (!isObject(schema) || schema.type !== 'enum' || typeof schema.name !== 'string') {
+    return undefined;
+  }
+
+  const namespace = typeof schema.namespace === 'string' ? schema.namespace : fallbackNamespace;
+  const fqName = getQualifiedName(schema.name, namespace);
+  if (!fqName) {
+    return undefined;
+  }
+
+  const existing = entities.get(fqName);
+  if (existing && existing.kind === 'enum' && existing.symbols.length > 0) {
+    return existing;
+  }
+
+  const symbols = Array.isArray(schema.symbols)
+    ? schema.symbols.filter((symbol): symbol is string => typeof symbol === 'string')
+    : [];
+
+  const entity: AvroEntity = {
+    fqName,
+    displayName: getShortName(fqName),
+    namespace,
+    kind: 'enum',
+    fields: [],
+    symbols,
+  };
+  entities.set(fqName, entity);
+  return entity;
+}
+
+function extractEntitiesFromSchema(schema: unknown, entities: Map<string, AvroEntity>): void {
+  if (Array.isArray(schema)) {
+    for (const item of schema) {
+      extractEntitiesFromSchema(item, entities);
+    }
+    return;
+  }
+
+  if (!isObject(schema)) {
+    return;
+  }
+
+  const record = extractRecord(schema, undefined, entities);
+  if (record) {
+    return;
+  }
+  const enumEntity = extractEnum(schema, undefined, entities);
+  if (enumEntity) {
+    return;
+  }
+
+  if (isObject(schema.type) || Array.isArray(schema.type)) {
+    extractEntitiesFromSchema(schema.type, entities);
+  }
+  if (Array.isArray(schema.fields)) {
+    for (const field of schema.fields) {
+      if (isObject(field)) {
+        extractEntitiesFromSchema(field.type, entities);
+      }
+    }
+  }
+}
+
+function getSameFolderAvroFiles(activeUri: string, files: Record<string, File>): File[] {
+  const activeDir = getDirectoryOfUri(activeUri);
+  return Object.values(files).filter((file) => {
+    if (file.uri === 'asyncapi' || file.uri === activeUri) {
+      return false;
+    }
+    if (!isAvroReferenceFile(file.uri)) {
+      return false;
+    }
+    return getDirectoryOfUri(file.uri) === activeDir;
+  });
+}
+
+function findReferenceFile(
+  referenceFqName: string,
+  activeUri: string,
+  files: Record<string, File>,
+): File | undefined {
+  const candidates = getSameFolderAvroFiles(activeUri, files);
+  const { typeName, namespace } = getTypeNameAndNamespace(referenceFqName);
+  const exactByType = `${typeName}.avsc`.toLowerCase();
+  const exactByNamespace = namespace ? `${namespace}.${typeName}.avsc`.toLowerCase() : '';
+
+  const byName = candidates.find((candidate) => getBasename(candidate.uri).toLowerCase() === exactByType);
+  if (byName) {
+    return byName;
+  }
+
+  if (exactByNamespace) {
+    const byNamespaceName = candidates.find(
+      (candidate) => getBasename(candidate.uri).toLowerCase() === exactByNamespace,
+    );
+    if (byNamespaceName) {
+      return byNamespaceName;
+    }
+  }
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate.content);
+      const tempEntities = new Map<string, AvroEntity>();
+      extractEntitiesFromSchema(parsed, tempEntities);
+      if (tempEntities.has(referenceFqName)) {
+        return candidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return undefined;
+}
+
+function ensurePlaceholdersForReferences(entities: Map<string, AvroEntity>): void {
+  const references = new Set<string>();
+  for (const entity of entities.values()) {
+    for (const field of entity.fields) {
+      for (const ref of field.references) {
+        references.add(ref);
+      }
+    }
+  }
+
+  for (const ref of references) {
+    if (!entities.has(ref)) {
+      const { namespace } = getTypeNameAndNamespace(ref);
+      entities.set(ref, {
+        fqName: ref,
+        displayName: getShortName(ref),
+        namespace,
+        kind: 'record',
+        fields: [],
+        symbols: [],
+      });
+    }
+  }
+}
+
+function resolveExternalReferences(
+  activeFile: File,
+  files: Record<string, File>,
+  entities: Map<string, AvroEntity>,
+): void {
+  const parsedFiles = new Set<string>([activeFile.uri]);
+  const queue: string[] = [];
+  const queued = new Set<string>();
+
+  const enqueueMissingRefs = () => {
+    for (const entity of entities.values()) {
+      for (const field of entity.fields) {
+        for (const ref of field.references) {
+          if (!entities.has(ref) && !queued.has(ref)) {
+            queue.push(ref);
+            queued.add(ref);
+          }
+        }
+      }
+    }
+  };
+
+  enqueueMissingRefs();
+  while (queue.length > 0) {
+    const targetRef = queue.shift();
+    if (!targetRef || entities.has(targetRef)) {
+      continue;
+    }
+
+    const refFile = findReferenceFile(targetRef, activeFile.uri, files);
+    if (!refFile) {
+      const { namespace } = getTypeNameAndNamespace(targetRef);
+      entities.set(targetRef, {
+        fqName: targetRef,
+        displayName: getShortName(targetRef),
+        namespace,
+        kind: 'record',
+        fields: [],
+        symbols: [],
+      });
+      continue;
+    }
+
+    if (!parsedFiles.has(refFile.uri)) {
+      parsedFiles.add(refFile.uri);
+      try {
+        const parsed = JSON.parse(refFile.content);
+        extractEntitiesFromSchema(parsed, entities);
+      } catch {
+        const { namespace } = getTypeNameAndNamespace(targetRef);
+        entities.set(targetRef, {
+          fqName: targetRef,
+          displayName: getShortName(targetRef),
+          namespace,
+          kind: 'record',
+          fields: [],
+          symbols: [],
+        });
+      }
+    }
+
+    if (!entities.has(targetRef)) {
+      const { namespace } = getTypeNameAndNamespace(targetRef);
+      entities.set(targetRef, {
+        fqName: targetRef,
+        displayName: getShortName(targetRef),
+        namespace,
+        kind: 'record',
+        fields: [],
+        symbols: [],
+      });
+    }
+
+    enqueueMissingRefs();
+  }
+}
+
+function renderMermaid(entities: Map<string, AvroEntity>): string {
+  const lines: string[] = ['classDiagram'];
+  const sortedEntities = Array.from(entities.values()).sort((a, b) => a.fqName.localeCompare(b.fqName));
+
+  for (const entity of sortedEntities) {
+    const classId = getClassId(entity.fqName);
+    lines.push(`class ${classId}["${escapeMermaidLabel(entity.fqName)}"]`);
+
+    if (entity.kind === 'enum' || entity.fields.length > 0) {
+      lines.push(`class ${classId} {`);
+      if (entity.kind === 'enum') {
+        lines.push('  <<enumeration>>');
+        for (const symbol of entity.symbols) {
+          lines.push(`  ${escapeMermaidLabel(symbol)}`);
+        }
+      } else {
+        for (const field of entity.fields) {
+          lines.push(`  ${escapeMermaidLabel(field.name)}: ${escapeMermaidLabel(field.typeLabel)}`);
+        }
+      }
+      lines.push('}');
+    }
+  }
+
+  const relationKeys = new Set<string>();
+  for (const entity of sortedEntities) {
+    const fromId = getClassId(entity.fqName);
+    for (const field of entity.fields) {
+      for (const ref of field.references) {
+        const toId = getClassId(ref);
+        const key = `${fromId}|${toId}|${field.name}`;
+        if (relationKeys.has(key)) {
+          continue;
+        }
+        relationKeys.add(key);
+        const relationLabel = field.collection ? `${field.name}[]` : field.name;
+        lines.push(`${fromId} --> ${toId} : ${escapeMermaidLabel(relationLabel)}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export function isAvroSchemaFile(file?: File): boolean {
+  if (!file) return false;
+  const uri = String(file.uri || '').toLowerCase();
+  return uri.endsWith('.avsc');
+}
+
+export function buildAvroDiagramMarkdown(file: File | undefined, files: Record<string, File>): string {
+  if (!file || !isAvroSchemaFile(file)) {
+    return [
+      AVRO_PREVIEW_TITLE,
+      '',
+      'Open an `.avsc` file to generate a Mermaid class diagram.',
+    ].join('\n');
+  }
+
+  let parsedSchema: unknown;
+  try {
+    parsedSchema = JSON.parse(file.content);
+  } catch {
+    return [
+      AVRO_PREVIEW_TITLE,
+      '',
+      'The active `.avsc` file is not valid JSON, so a diagram cannot be generated.',
+    ].join('\n');
+  }
+
+  const entities = new Map<string, AvroEntity>();
+  extractEntitiesFromSchema(parsedSchema, entities);
+
+  if (entities.size === 0) {
+    return [
+      AVRO_PREVIEW_TITLE,
+      '',
+      'No Avro records or enums were found in this file.',
+    ].join('\n');
+  }
+
+  resolveExternalReferences(file, files, entities);
+  ensurePlaceholdersForReferences(entities);
+
+  const mermaid = renderMermaid(entities);
+  return [
+    '```mermaid',
+    mermaid,
+    '```',
+  ].join('\n');
+}
diff --git a/apps/studio/src/components/Template/index.ts b/apps/studio/src/components/Template/index.ts
index 1972b01e5..4918c4401 100644
--- a/apps/studio/src/components/Template/index.ts
+++ b/apps/studio/src/components/Template/index.ts
@@ -1,2 +1,3 @@
 export * from './Template';
 export * from './HTMLWrapper';
+export * from './AvroPreview';
diff --git a/apps/studio/src/schemas/avro/avro-schema.json b/apps/studio/src/schemas/avro/avro-schema.json
new file mode 100644
index 000000000..d5538d969
--- /dev/null
+++ b/apps/studio/src/schemas/avro/avro-schema.json
@@ -0,0 +1,290 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://json.schemastore.org/avro-avsc.json",
+  "definitions": {
+    "avroSchema": {
+      "title": "Avro Schema",
+      "description": "Root Schema",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/types"
+        }
+      ]
+    },
+    "types": {
+      "title": "Avro Types",
+      "description": "Allowed Avro types",
+      "oneOf": [
+        {
+          "$ref": "#/definitions/primitiveType"
+        },
+        {
+          "$ref": "#/definitions/primitiveTypeWithMetadata"
+        },
+        {
+          "$ref": "#/definitions/customTypeReference"
+        },
+        {
+          "$ref": "#/definitions/avroRecord"
+        },
+        {
+          "$ref": "#/definitions/avroEnum"
+        },
+        {
+          "$ref": "#/definitions/avroArray"
+        },
+        {
+          "$ref": "#/definitions/avroMap"
+        },
+        {
+          "$ref": "#/definitions/avroFixed"
+        },
+        {
+          "$ref": "#/definitions/avroUnion"
+        }
+      ]
+    },
+    "primitiveType": {
+      "title": "Primitive Type",
+      "description": "Basic type primitives.",
+      "type": "string",
+      "enum": [
+        "null",
+        "boolean",
+        "int",
+        "long",
+        "float",
+        "double",
+        "bytes",
+        "string"
+      ]
+    },
+    "primitiveTypeWithMetadata": {
+      "title": "Primitive Type With Metadata",
+      "description": "A primitive type with metadata attached.",
+      "type": "object",
+      "properties": {
+        "type": {
+          "$ref": "#/definitions/primitiveType"
+        }
+      },
+      "required": ["type"]
+    },
+    "customTypeReference": {
+      "title": "Custom Type",
+      "description": "Reference to a ComplexType",
+      "not": {
+        "$ref": "#/definitions/primitiveType"
+      },
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$"
+    },
+    "avroUnion": {
+      "title": "Union",
+      "description": "A Union of types",
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/avroSchema"
+      },
+      "minItems": 1
+    },
+    "avroField": {
+      "title": "Field",
+      "description": "A field within a Record",
+      "type": "object",
+      "properties": {
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "type": {
+          "$ref": "#/definitions/types"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "default": {},
+        "order": {
+          "enum": ["ascending", "descending", "ignore"]
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        }
+      },
+      "required": ["name", "type"]
+    },
+    "avroRecord": {
+      "title": "Record",
+      "description": "A Record",
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["record"]
+        },
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "namespace": {
+          "$ref": "#/definitions/namespace"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        },
+        "fields": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/avroField"
+          }
+        }
+      },
+      "required": ["type", "name", "fields"]
+    },
+    "avroEnum": {
+      "title": "Enum",
+      "description": "An enumeration",
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["enum"]
+        },
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "namespace": {
+          "$ref": "#/definitions/namespace"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        },
+        "symbols": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        }
+      },
+      "required": ["type", "name", "symbols"]
+    },
+    "avroArray": {
+      "title": "Array",
+      "description": "An array",
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["array"]
+        },
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "namespace": {
+          "$ref": "#/definitions/namespace"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        },
+        "items": {
+          "$ref": "#/definitions/types"
+        }
+      },
+      "required": ["type", "items"]
+    },
+    "avroMap": {
+      "title": "Map",
+      "description": "A map of values",
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["map"]
+        },
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "namespace": {
+          "$ref": "#/definitions/namespace"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        },
+        "values": {
+          "$ref": "#/definitions/types"
+        }
+      },
+      "required": ["type", "values"]
+    },
+    "avroFixed": {
+      "title": "Fixed",
+      "description": "A fixed sized array of bytes",
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["fixed"]
+        },
+        "name": {
+          "$ref": "#/definitions/name"
+        },
+        "namespace": {
+          "$ref": "#/definitions/namespace"
+        },
+        "doc": {
+          "type": "string"
+        },
+        "aliases": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/name"
+          }
+        },
+        "size": {
+          "type": "number"
+        }
+      },
+      "required": ["type", "name", "size"]
+    },
+    "name": {
+      "type": "string",
+      "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+    },
+    "namespace": {
+      "type": "string",
+      "pattern": "^([A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*)*$"
+    }
+  },
+  "description": "Json-Schema definition for Avro AVSC files.",
+  "oneOf": [
+    {
+      "$ref": "#/definitions/avroSchema"
+    }
+  ],
+  "title": "Avro Schema Definition"
+}
diff --git a/apps/studio/src/services/app.service.ts b/apps/studio/src/services/app.service.ts
index 338bf956b..9815d49c9 100644
--- a/apps/studio/src/services/app.service.ts
+++ b/apps/studio/src/services/app.service.ts
@@ -66,7 +66,14 @@ export class ApplicationService extends AbstractService {
     }
 
     const detectedLanguage = this.svcs.formatSvc.retrieveLangauge(content);
-    const language: 'json' | 'yaml' = detectedLanguage === 'json' ? 'json' : 'yaml';
+    const sourceUri = url || (share ? `share://${share}` : 'base64://document');
+    const lowerUri = sourceUri.toLowerCase();
+    let language: 'json' | 'yaml' | 'markdown' = 'yaml';
+    if (lowerUri.endsWith('.md') || lowerUri.endsWith('.markdown')) {
+      language = 'markdown';
+    } else if (detectedLanguage === 'json') {
+      language = 'json';
+    }
     const source = url || undefined;
     let from: 'url' | 'base64' | 'share' = 'url';
     if (base64) {
@@ -74,7 +81,7 @@ export class ApplicationService extends AbstractService {
     } else if (share) {
       from = 'share';
     }
-    const uri = url || (share ? `share://${share}` : 'base64://document');
+    const uri = sourceUri;
     const file = {
       uri,
       name: uri.split('/').pop() || uri,
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 6c7f740ac..9ce03cecf 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -29,12 +29,18 @@ export class EditorService extends AbstractService {
     this.subcribeToDocuments();
   }
 
-  async onDidCreate(editor: monacoAPI.editor.IStandaloneCodeEditor) {
+  async onDidCreate(editor: monacoAPI.editor.IStandaloneCodeEditor) {
     if (this.created) {
       return;
-    }
-    this.created = true;
-    this.instance = editor;
+    }
+    this.created = true;
+    this.instance = editor;
+    const currentFile = filesState.getState().files['asyncapi'];
+    const currentUri = currentFile?.uri || 'asyncapi';
+    this.svcs.monacoSvc.setSchemaValidationForFile(
+      currentUri,
+      this.isAsyncApiContent(editor.getValue(), currentUri),
+    );
 
     // parse on first run - only when document is undefined
     const document = documentsState.getState().documents.asyncapi;
@@ -73,28 +79,36 @@ export class EditorService extends AbstractService {
     return parts[parts.length - 1] || uri;
   }
 
-  private inferLanguageFromUri(uri: string, content?: string): 'json' | 'yaml' {
-    const byContent = content ? this.svcs.formatSvc.retrieveLangauge(content) : undefined;
-    if (byContent === 'json' || byContent === 'yaml') {
-      return byContent;
-    }
-    const lower = uri.toLowerCase();
-    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
-      return 'json';
-    }
+  private inferLanguageFromUri(uri: string, content?: string): 'json' | 'yaml' | 'markdown' {
+    const lower = uri.toLowerCase();
+    if (lower.endsWith('.md') || lower.endsWith('.markdown')) {
+      return 'markdown';
+    }
+    const byContent = content ? this.svcs.formatSvc.retrieveLangauge(content) : undefined;
+    if (byContent === 'json' || byContent === 'yaml') {
+      return byContent;
+    }
+    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
+      return 'json';
+    }
     return 'yaml';
   }
 
-  private isAsyncApiContent(content: string): boolean {
-    const trimmed = String(content || '').trim();
-    if (!trimmed) return false;
-    if (trimmed.startsWith('{')) {
-      try {
-        const parsed = JSON.parse(trimmed);
-        return !!parsed?.asyncapi;
-      } catch {
-        return false;
-      }
+  private isAsyncApiContent(content: string, uri = ''): boolean {
+    const lowerUri = String(uri || '').toLowerCase();
+    if (lowerUri.endsWith('.avsc') || lowerUri.endsWith('.md') || lowerUri.endsWith('.markdown')) {
+      return false;
+    }
+
+    const trimmed = String(content || '').trim();
+    if (!trimmed) return false;
+    if (trimmed.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(trimmed);
+        return typeof parsed?.asyncapi === 'string';
+      } catch {
+        return false;
+      }
     }
     return (/^asyncapi\s*:/m).test(trimmed);
   }
@@ -134,16 +148,17 @@ export class EditorService extends AbstractService {
       }
 
       const language = this.inferLanguageFromUri(uri, content);
-      updateFile(uri, {
-        content,
-        language,
-        name: target.name || this.getFileNameFromUri(uri),
-        isAsyncApiDocument: this.isAsyncApiContent(content),
-        stat: { mtime: Date.now() },
-      });
-      setActiveFile(uri);
-      this.updateState({
-        content,
+      updateFile(uri, {
+        content,
+        language,
+        name: target.name || this.getFileNameFromUri(uri),
+        isAsyncApiDocument: this.isAsyncApiContent(content, uri),
+        stat: { mtime: Date.now() },
+      });
+      this.svcs.monacoSvc.setSchemaValidationForFile(uri, this.isAsyncApiContent(content, uri));
+      setActiveFile(uri);
+      this.updateState({
+        content,
         updateModel: true,
         sendToServer: false,
         file: {
@@ -154,10 +169,10 @@ export class EditorService extends AbstractService {
           directoryHandle: target.directoryHandle,
           localPath: target.localPath,
           name: target.name || this.getFileNameFromUri(uri),
-          isAsyncApiDocument: this.isAsyncApiContent(content),
-          stat: { mtime: Date.now() },
-        },
-      });
+          isAsyncApiDocument: this.isAsyncApiContent(content, uri),
+          stat: { mtime: Date.now() },
+        },
+      });
     } finally {
       setFileTreeLoading(false);
     }
@@ -193,9 +208,9 @@ export class EditorService extends AbstractService {
             directoryHandle,
             fileHandle,
             localPath,
-            isAsyncApiDocument: this.isAsyncApiContent(content),
-            stat: { mtime: Date.now() },
-          };
+            isAsyncApiDocument: this.isAsyncApiContent(content, localPath),
+            stat: { mtime: Date.now() },
+          };
         } catch (err) {
           console.error('[DEBUG:editor] Failed to read local file for tree', localPath, err);
         }
@@ -216,14 +231,18 @@ export class EditorService extends AbstractService {
       return;
     }
 
-    const language = file.language || this.svcs.formatSvc.retrieveLangauge(content);
-    if (!language) {
-      return;
-    }
-
-    if (sendToServer) {
-      this.svcs.socketClientSvc.send('file:update', { code: content });
-    }
+    const currentFile = filesState.getState().files['asyncapi'];
+    const language = file.language || this.inferLanguageFromUri(currentFile?.uri || 'asyncapi', content);
+    if (!language) {
+      return;
+    }
+    const isAsyncApiDocument = file.isAsyncApiDocument ?? this.isAsyncApiContent(content, currentFile?.uri || '');
+    const currentUri = filesState.getState().activeFileUri || file.uri || 'asyncapi';
+    this.svcs.monacoSvc.setSchemaValidationForFile(currentUri, isAsyncApiDocument);
+
+    if (sendToServer) {
+      this.svcs.socketClientSvc.send('file:update', { code: content });
+    }
 
     if (updateModel && this.editor) {
       const model = this.editor.getModel();
@@ -269,10 +288,10 @@ export class EditorService extends AbstractService {
     toast.loading('Please select the AsyncAPI file within the folder...', { id: folderAccessToastId });
     let fileHandle: FileHandle;
     try {
-      const [handle] = await window.showOpenFilePicker({
-        types: [{ description: 'AsyncAPI files', accept: { 'text/*': ['.yaml', '.yml', '.json'] } }],
-        multiple: false,
-      });
+      const [handle] = await window.showOpenFilePicker({
+        types: [{ description: 'Supported files', accept: { 'text/*': ['.yaml', '.yml', '.json', '.md', '.markdown'] } }],
+        multiple: false,
+      });
       fileHandle = handle;
     } catch (err: any) {
       toast.dismiss(folderAccessToastId);
@@ -305,9 +324,9 @@ export class EditorService extends AbstractService {
       fileHandle,
       localPath,
       modified: false,
-      isAsyncApiDocument: this.isAsyncApiContent(selectedContent),
-      stat: { mtime: Date.now() },
-    };
+      isAsyncApiDocument: this.isAsyncApiContent(selectedContent, localPath),
+      stat: { mtime: Date.now() },
+    };
 
     filesState.getState().setProjectFiles(files, {
       activeFileUri: localPath,
@@ -354,9 +373,9 @@ export class EditorService extends AbstractService {
           source: url,
           language,
           modified: false,
-          isAsyncApiDocument: this.isAsyncApiContent(text),
-          stat: { mtime: Date.now() },
-        };
+          isAsyncApiDocument: this.isAsyncApiContent(text, url),
+          stat: { mtime: Date.now() },
+        };
 
         filesState.getState().setProjectFiles(
           { [url]: mainFile },
@@ -384,10 +403,10 @@ export class EditorService extends AbstractService {
       return;
     }
 
-    const allowedExtensions = ['json', 'yaml', 'yml', 'avsc'];
+    const allowedExtensions = ['json', 'yaml', 'yml', 'avsc', 'md', 'markdown'];
     const ext = file.name.split('.').pop()?.toLowerCase() ?? '';
     if (!allowedExtensions.includes(ext)) {
-      throw new Error('Invalid file type. Only .json, .yaml, .yml, and .avsc files are supported.');
+      throw new Error('Invalid file type. Only .json, .yaml, .yml, .avsc, .md, and .markdown files are supported.');
     }
 
     console.log('[DEBUG:editor] importFile', file.name);
@@ -405,9 +424,9 @@ export class EditorService extends AbstractService {
         source: undefined,
         language,
         modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(content),
-        stat: { mtime: Date.now() },
-      };
+        isAsyncApiDocument: this.isAsyncApiContent(content, uri),
+        stat: { mtime: Date.now() },
+      };
 
       filesState.getState().setProjectFiles(
         { [uri]: importedFile },
@@ -436,9 +455,9 @@ export class EditorService extends AbstractService {
         source: undefined,
         language,
         modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(String(decoded)),
-        stat: { mtime: Date.now() },
-      };
+        isAsyncApiDocument: this.isAsyncApiContent(String(decoded), uri),
+        stat: { mtime: Date.now() },
+      };
 
       filesState.getState().setProjectFiles(
         { [uri]: importedFile },
@@ -474,9 +493,9 @@ export class EditorService extends AbstractService {
         source: undefined,
         language,
         modified: false,
-        isAsyncApiDocument: this.isAsyncApiContent(data.content),
-        stat: { mtime: Date.now() },
-      };
+        isAsyncApiDocument: this.isAsyncApiContent(data.content, uri),
+        stat: { mtime: Date.now() },
+      };
 
       filesState.getState().setProjectFiles(
         { [uri]: importedFile },
@@ -575,17 +594,33 @@ export class EditorService extends AbstractService {
       throw new Error('Failed to get current document content for saving.');
     }
 
+    let extension = 'yaml';
+    let mimeType = 'text/yaml';
+    if (language === 'json') {
+      extension = 'json';
+      mimeType = 'application/json';
+    } else if (language === 'markdown') {
+      extension = 'md';
+      mimeType = 'text/markdown';
+    }
+
     return {
       file: currentFile,
       language,
       content,
-      extension: language === 'yaml' ? 'yaml' : 'json',
-      mimeType: language === 'yaml' ? 'text/yaml' : 'application/json',
+      extension,
+      mimeType,
     };
   }
 
   async saveCurrentFile() {
     const { file, language, content, extension, mimeType } = this.getCurrentContentByLanguage();
+    let fileTypeDescription = 'YAML file';
+    if (language === 'json') {
+      fileTypeDescription = 'JSON file';
+    } else if (language === 'markdown') {
+      fileTypeDescription = 'Markdown file';
+    }
 
     if (file.from === 'file' && file.fileHandle) {
       const writable = await file.fileHandle.createWritable();
@@ -611,7 +646,7 @@ export class EditorService extends AbstractService {
       suggestedName: suggestedFileName,
       types: [
         {
-          description: language === 'yaml' ? 'YAML file' : 'JSON file',
+          description: fileTypeDescription,
           accept: { [mimeType]: [`.${extension}`] },
         },
       ],
diff --git a/apps/studio/src/services/format.service.ts b/apps/studio/src/services/format.service.ts
index f0341e479..8c11171e9 100644
--- a/apps/studio/src/services/format.service.ts
+++ b/apps/studio/src/services/format.service.ts
@@ -3,6 +3,8 @@ import { AbstractService } from './abstract.service';
 import { encode, decode } from 'js-base64';
 import YAML from 'js-yaml';
 
+export type SpecType = 'asyncapi' | 'openapi' | 'unknown';
+
 export class FormatService extends AbstractService {
   convertToYaml(spec: string) {
     try {
@@ -39,4 +41,32 @@ export class FormatService extends AbstractService {
     }
     return 'yaml';
   }
+
+  detectSpecType(content: string): SpecType {
+    const text = String(content || '').trim();
+    if (!text) {
+      return 'unknown';
+    }
+
+    let parsed: any;
+    try {
+      parsed = text.startsWith('{') ? JSON.parse(text) : YAML.load(text);
+    } catch {
+      return 'unknown';
+    }
+
+    if (!parsed || typeof parsed !== 'object') {
+      return 'unknown';
+    }
+
+    if (typeof parsed.asyncapi === 'string') {
+      return 'asyncapi';
+    }
+
+    if (typeof parsed.openapi === 'string' || typeof parsed.swagger === 'string') {
+      return 'openapi';
+    }
+
+    return 'unknown';
+  }
 }
diff --git a/apps/studio/src/services/monaco.service.ts b/apps/studio/src/services/monaco.service.ts
index d9edb5022..c9cb1abb6 100644
--- a/apps/studio/src/services/monaco.service.ts
+++ b/apps/studio/src/services/monaco.service.ts
@@ -3,6 +3,7 @@ import { AbstractService } from './abstract.service';
 import { loader } from '@monaco-editor/react';
 import { setDiagnosticsOptions } from 'monaco-yaml';
 import YAML from 'js-yaml';
+import avroSchema from '@/schemas/avro/avro-schema.json';
 
 import { documentsState, filesState } from '@/state';
 
@@ -16,6 +17,8 @@ export class MonacoService extends AbstractService {
   private jsonSchemaDefinitions: monacoAPI.languages.json.DiagnosticsOptions['schemas'] = [];
   private actualVersion = 'X.X.X';
   private monacoInstance!: typeof monacoAPI;
+  private activeFileUri = 'asyncapi';
+  private isAsyncApiValidationEnabled = true;
 
   override async onInit() {
     // load monaco instance
@@ -42,6 +45,21 @@ export class MonacoService extends AbstractService {
     this.actualVersion = version;
   }
 
+  setSchemaValidationForFile(
+    fileUri: string,
+    isAsyncApiDocument: boolean,
+    version: SpecVersions = this.actualVersion as SpecVersions,
+  ) {
+    if (!this.monaco) {
+      return;
+    }
+    this.activeFileUri = this.normalizeUri(fileUri);
+    this.isAsyncApiValidationEnabled = isAsyncApiDocument;
+    const fallbackVersion = this.svcs.specificationSvc.latestVersion;
+    const resolvedVersion = this.jsonSchemaSpecs.has(version) ? version : fallbackVersion;
+    this.setLanguageConfig(resolvedVersion as SpecVersions);
+  }
+
   private setLanguageConfig(version: SpecVersions = this.svcs.specificationSvc.latestVersion) {
     if (!this.monaco) {
       return;
@@ -58,28 +76,59 @@ export class MonacoService extends AbstractService {
     setDiagnosticsOptions(options as YAMLDiagnosticsOptions);
   }
 
-  private prepareLanguageConfig(
-    version: SpecVersions,
-  ): monacoAPI.languages.json.DiagnosticsOptions {
-    const spec = this.jsonSchemaSpecs.get(version);
+  private prepareLanguageConfig(version: SpecVersions): monacoAPI.languages.json.DiagnosticsOptions {
+    const fallbackVersion = this.svcs.specificationSvc.latestVersion;
+    const spec = this.jsonSchemaSpecs.get(version) || this.jsonSchemaSpecs.get(fallbackVersion);
+
+    const schemas: monacoAPI.languages.json.DiagnosticsOptions['schemas'] = [];
+    const avroSchemaId = String((avroSchema as any).$id || 'https://json.schemastore.org/avro-avsc.json');
+    schemas.push({
+      uri: avroSchemaId,
+      fileMatch: ['*.avsc', '**/*.avsc'],
+      schema: avroSchema as any,
+    });
+
+    const asyncApiSchemas: monacoAPI.languages.json.DiagnosticsOptions['schemas'] = [];
+    if (this.isAsyncApiValidationEnabled && spec) {
+      const asyncApiFileMatches = this.fileMatchesForUri(this.activeFileUri);
+      asyncApiSchemas.push({
+        uri: String(spec.$id || 'https://www.asyncapi.com/definitions/latest'),
+        fileMatch: asyncApiFileMatches,
+        schema: spec,
+      });
+      asyncApiSchemas.push(...(this.jsonSchemaDefinitions || []));
+    }
 
     return {
       enableSchemaRequest: false,
       hover: true,
       completion: true,
-      validate: true,
+      validate: schemas.length > 0,
       format: true,
       schemas: [
-        {
-          uri: spec.$id, // id of the AsyncAPI spec schema
-          fileMatch: ['*'], // associate with all models
-          schema: spec,
-        },
-        ...(this.jsonSchemaDefinitions || []),
+        ...schemas,
+        ...asyncApiSchemas,
       ],
     } as any;
   }
 
+  private normalizeUri(uri: string): string {
+    if (!uri) {
+      return 'asyncapi';
+    }
+    return String(uri).replace(/\\/g, '/');
+  }
+
+  private fileMatchesForUri(uri: string): string[] {
+    const normalized = this.normalizeUri(uri);
+    const baseName = normalized.split('/').pop();
+    const matches = [normalized];
+    if (baseName && baseName !== normalized) {
+      matches.push(`**/${baseName}`);
+    }
+    return matches;
+  }
+
   private async loadMonaco() {
     // in test environment we don't need monaco loaded
     if (process.env.NODE_ENV === 'test') {
@@ -167,6 +216,9 @@ export class MonacoService extends AbstractService {
 
   private subcribeToDocuments() {
     documentsState.subscribe((state, prevState) => {
+      if (!this.isAsyncApiValidationEnabled) {
+        return;
+      }
       const newDocuments = state.documents;
       const oldDocuments = prevState.documents;
 
@@ -180,8 +232,11 @@ export class MonacoService extends AbstractService {
           try {
             const file = filesState.getState().files['asyncapi'];
             if (file) {
-              const version = (YAML.load(file.content) as { asyncapi: SpecVersions }).asyncapi;
-              this.svcs.monacoSvc.updateLanguageConfig(version);
+              const parsed = YAML.load(file.content) as { asyncapi?: SpecVersions } | undefined;
+              const fallbackVersion = parsed?.asyncapi;
+              if (fallbackVersion && this.jsonSchemaSpecs.has(fallbackVersion)) {
+                this.svcs.monacoSvc.updateLanguageConfig(fallbackVersion);
+              }
             }
           } catch (e: any) {
             // intentional
diff --git a/apps/studio/src/services/navigation.service.ts b/apps/studio/src/services/navigation.service.ts
index 2e4c5976e..79c7c32aa 100644
--- a/apps/studio/src/services/navigation.service.ts
+++ b/apps/studio/src/services/navigation.service.ts
@@ -34,11 +34,12 @@ export class NavigationService extends AbstractService {
 
   async scrollTo(
     jsonPointer: string | Array<string | number>,
-    hash: string,
+    hash?: string,
   ) {
     try {
       const doc = this.svcs.editorSvc;
-      const methodType = doc.value.startsWith('asyncapi') ? 'getRangeForYamlPath' : 'getRangeForJsonPath';
+      const content = String(doc.value || '');
+      const methodType = content.startsWith('asyncapi') ? 'getRangeForYamlPath' : 'getRangeForJsonPath';
       const range = this.svcs.parserSvc[methodType]('asyncapi', jsonPointer);
       
       if (range) {
@@ -46,7 +47,9 @@ export class NavigationService extends AbstractService {
       }
 
       await this.scrollToHash(hash);
-      this.emitHashChangeEvent(hash);
+      if (hash) {
+        this.emitHashChangeEvent(hash);
+      }
     } catch (e) {
       console.error(e);
     }
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index dac38de5f..a7781c8fe 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -56,8 +56,16 @@ export class ParserService extends AbstractService {
       return;
     }
 
-    if (!this.isAsyncApiDocument(spec)) {
+    const activeUri = active?.uri || options.source || '';
+    if (!this.isAsyncApiDocument(spec, String(activeUri))) {
       filesState.getState().updateFile('asyncapi', { isAsyncApiDocument: false });
+      this.updateDocument(uri, {
+        uri,
+        document: undefined,
+        diagnostics: this.createDiagnostics([]),
+        extras: undefined,
+        valid: false,
+      });
       return;
     }
     filesState.getState().updateFile('asyncapi', { isAsyncApiDocument: true });
@@ -93,7 +101,7 @@ export class ParserService extends AbstractService {
             fileHandle,
             localPath: relativePath,
             stat: { mtime: Date.now() },
-            isAsyncApiDocument: this.isAsyncApiDocument(content),
+            isAsyncApiDocument: this.isAsyncApiDocument(content, relativePath),
           });
         },
       });
@@ -192,21 +200,30 @@ export class ParserService extends AbstractService {
 
   private updateDocument = documentsState.getState().updateDocument;
 
-  private inferLanguage(uri: string, content: string): 'json' | 'yaml' {
-    if (uri.toLowerCase().endsWith('.json') || uri.toLowerCase().endsWith('.avsc')) {
+  private inferLanguage(uri: string, content: string): 'json' | 'yaml' | 'markdown' {
+    const lower = uri.toLowerCase();
+    if (lower.endsWith('.md') || lower.endsWith('.markdown')) {
+      return 'markdown';
+    }
+    if (lower.endsWith('.json') || lower.endsWith('.avsc')) {
       return 'json';
     }
     const trimmed = String(content || '').trim();
     return trimmed.startsWith('{') ? 'json' : 'yaml';
   }
 
-  private isAsyncApiDocument(spec: string): boolean {
+  private isAsyncApiDocument(spec: string, uri = ''): boolean {
+    const lowerUri = String(uri || '').toLowerCase();
+    if (lowerUri.endsWith('.avsc') || lowerUri.endsWith('.md') || lowerUri.endsWith('.markdown')) {
+      return false;
+    }
+
     const trimmed = String(spec || '').trim();
     if (!trimmed) return false;
     if (trimmed.startsWith('{')) {
       try {
         const parsed = JSON.parse(trimmed);
-        return !!parsed?.asyncapi;
+        return typeof parsed?.asyncapi === 'string';
       } catch {
         return false;
       }
@@ -236,7 +253,7 @@ export class ParserService extends AbstractService {
           language: inferLanguage(url, content),
           modified: false,
           stat: { mtime: Date.now() },
-          isAsyncApiDocument: isAsyncApiDocument(content),
+          isAsyncApiDocument: isAsyncApiDocument(content, url),
         });
         return content;
       },
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index 47e1c32d0..0874d2b93 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -246,7 +246,7 @@ export type File = {
   content: string;
   from: 'storage' | 'url' | 'base64' | 'share' | 'file';
   source?: string;
-  language: 'json' | 'yaml';
+  language: 'json' | 'yaml' | 'markdown';
   modified: boolean;
   stat?: FileStat;
   fileHandle?: FileHandle;
diff --git a/apps/studio/src/state/panels.state.ts b/apps/studio/src/state/panels.state.ts
index d920f56a1..c15917408 100644
--- a/apps/studio/src/state/panels.state.ts
+++ b/apps/studio/src/state/panels.state.ts
@@ -12,7 +12,7 @@ export type PanelsState = {
     contextPanel: boolean;
   };
   // TODO: remove when panels tabs will be introduced
-  secondaryPanelType: 'template' | 'visualiser';
+  secondaryPanelType: 'template' | 'visualiser' | 'avro';
 }
 
 export const panelsState = create(
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 5d9ca31d1..04f7ee416 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -241,6 +241,9 @@ importers:
       js-yaml:
         specifier: ^4.1.1
         version: 4.1.1
+      mermaid:
+        specifier: ^11.13.0
+        version: 11.13.0
       monaco-editor:
         specifier: 0.34.1
         version: 0.34.1
@@ -519,6 +522,9 @@ packages:
     resolution: {integrity: sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw==}
     engines: {node: '>=6.0.0'}
 
+  '@antfu/install-pkg@1.1.0':
+    resolution: {integrity: sha512-MGQsmw10ZyI+EJo45CdSER4zEb+p31LpDAFp2Z3gkSd1yqVZGi0Ebx++YTEMonJy4oChEMLsxZ64j8FH6sSqtQ==}
+
   '@apideck/better-ajv-errors@0.3.6':
     resolution: {integrity: sha512-P+ZygBLZtkp0qqOAJJVX4oX/sFo5JR3eBWwwuqHHhK0GIgQOKWrAfiAaWX0aArHkRWHMuggFEgAZNxVPwPZYaA==}
     engines: {node: '>=10'}
@@ -1951,6 +1957,9 @@ packages:
   '@bcoe/v8-coverage@0.2.3':
     resolution: {integrity: sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==}
 
+  '@braintree/sanitize-url@7.1.2':
+    resolution: {integrity: sha512-jigsZK+sMF/cuiB7sERuo9V7N9jx+dhmHHnQyDSVdpZwVutaBu7WvNYqMDLSgFgfB30n452TP3vjDAvFC973mA==}
+
   '@changesets/apply-release-plan@6.1.4':
     resolution: {integrity: sha512-FMpKF1fRlJyCZVYHr3CbinpZZ+6MwvOtWUuO8uo+svcATEoc1zRDcj23pAurJ2TZ/uVz1wFHH6K3NlACy0PLew==}
 
@@ -2003,6 +2012,21 @@ packages:
   '@changesets/write@0.2.3':
     resolution: {integrity: sha512-Dbamr7AIMvslKnNYsLFafaVORx4H0pvCA2MHqgtNCySMe1blImEyAEOzDmcgKAkgz4+uwoLz7demIrX+JBr/Xw==}
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    resolution: {integrity: sha512-XTsjvDVB5nDZBQB8o0o/0ozNelQtn2KrUVteIHSlPd2VAV2utEb6JzyCJaJ8tGxACR4RiBNWy5uYUHX2eji88Q==}
+
+  '@chevrotain/gast@11.1.2':
+    resolution: {integrity: sha512-Z9zfXR5jNZb1Hlsd/p+4XWeUFugrHirq36bKzPWDSIacV+GPSVXdk+ahVWZTwjhNwofAWg/sZg58fyucKSQx5g==}
+
+  '@chevrotain/regexp-to-ast@11.1.2':
+    resolution: {integrity: sha512-nMU3Uj8naWer7xpZTYJdxbAs6RIv/dxYzkYU8GSwgUtcAAlzjcPfX1w+RKRcYG8POlzMeayOQ/znfwxEGo5ulw==}
+
+  '@chevrotain/types@11.1.2':
+    resolution: {integrity: sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==}
+
+  '@chevrotain/utils@11.1.2':
+    resolution: {integrity: sha512-4mudFAQ6H+MqBTfqLmU7G1ZwRzCLfJEooL/fsF6rCX5eePMbGhoy5n4g+G4vlh2muDcsCTJtL+uKbOzWxs5LHA==}
+
   '@codemirror/autocomplete@6.18.1':
     resolution: {integrity: sha512-iWHdj/B1ethnHRTwZj+C1obmmuCzquH29EbcKr0qIjA9NfDeBDJ7vs+WOHsFeLeflE4o+dHfYndJloMKHUkWUA==}
     peerDependencies:
@@ -2529,6 +2553,12 @@ packages:
   '@hyperjump/pact@0.2.5':
     resolution: {integrity: sha512-93m7gLf40EI8svsKrdPc+KkLsngwX/2ld08xwc0PFioxJSxnfkx1BUHNJVjhG386UUYP6mNe+ZtmIiDXDJ4TQg==}
 
+  '@iconify/types@2.0.0':
+    resolution: {integrity: sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==}
+
+  '@iconify/utils@3.1.0':
+    resolution: {integrity: sha512-Zlzem1ZXhI1iHeeERabLNzBHdOa4VhQbqAcOQaMKuTuyZCpwKbC2R4Dd0Zo3g9EAc+Y4fiarO8HIHRAth7+skw==}
+
   '@isaacs/cliui@8.0.2':
     resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
     engines: {node: '>=12'}
@@ -2705,6 +2735,9 @@ packages:
     peerDependencies:
       react: '>=16'
 
+  '@mermaid-js/parser@1.0.1':
+    resolution: {integrity: sha512-opmV19kN1JsK0T6HhhokHpcVkqKpF+x2pPDKKM2ThHtZAB5F4PROopk0amuVYK5qMrIA4erzpNm8gmPNJgMDxQ==}
+
   '@monaco-editor/loader@1.4.0':
     resolution: {integrity: sha512-00ioBig0x642hytVspPl7DbQyaSWRaolYie/UFNjoTdvoKPzo6xrXLhTk9ixgIKcLH5b5vDOjVNiGyY+uDCUlg==}
     peerDependencies:
@@ -4779,6 +4812,9 @@ packages:
   '@ungap/structured-clone@1.3.0':
     resolution: {integrity: sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==}
 
+  '@upsetjs/venn.js@2.0.0':
+    resolution: {integrity: sha512-WbBhLrooyePuQ1VZxrJjtLvTc4NVfpOyKx0sKqioq9bX1C1m7Jgykkn8gLrtwumBioXIqam8DLxp88Adbue6Hw==}
+
   '@vitest/expect@0.34.7':
     resolution: {integrity: sha512-G9iEtwrD6ZQ4MVHZufif9Iqz3eLtuwBBNx971fNAGPaugM7ftAWjQN+ob2zWhtzURp8RK3zGXOxVb01mFo3zAQ==}
 
@@ -5650,6 +5686,14 @@ packages:
   check-types@11.2.3:
     resolution: {integrity: sha512-+67P1GkJRaxQD6PKK0Et9DhwQB+vGg3PM5+aavopCpZT1lj9jeqfvpgTLAWErNj8qApkkmXlu/Ug74kmhagkXg==}
 
+  chevrotain-allstar@0.3.1:
+    resolution: {integrity: sha512-b7g+y9A0v4mxCW1qUhf3BSVPg+/NvGErk/dOkrDaHA0nQIQGAtrOjlX//9OQtRlSCy+x9rfB5N8yC71lH1nvMw==}
+    peerDependencies:
+      chevrotain: ^11.0.0
+
+  chevrotain@11.1.2:
+    resolution: {integrity: sha512-opLQzEVriiH1uUQ4Kctsd49bRoFDXGGSC4GUqj7pGyxM3RehRhvTlZJc1FL/Flew2p5uwxa1tUDWKzI4wNM8pg==}
+
   chokidar@3.6.0:
     resolution: {integrity: sha512-7VT13fmjotKpGipCW9JEQAusEPE+Ei8nl6/g4FBAmIm0GOOLMua9NDDo/DWp0ZAxCr3cPq5ZpBqmPAQgDda2Pw==}
     engines: {node: '>= 8.10.0'}
@@ -5917,6 +5961,12 @@ packages:
   core-util-is@1.0.3:
     resolution: {integrity: sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==}
 
+  cose-base@1.0.3:
+    resolution: {integrity: sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==}
+
+  cose-base@2.2.0:
+    resolution: {integrity: sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==}
+
   cosmiconfig@6.0.0:
     resolution: {integrity: sha512-xb3ZL6+L8b9JLLCx3ZdoZy4+2ECphCMo2PwqgP1tlfVq6M6YReyzBJtvWWtbDSpNr9hn96pkCiZqUcFEc+54Qg==}
     engines: {node: '>=8'}
@@ -6111,10 +6161,51 @@ packages:
     engines: {node: ^16.0.0 || ^18.0.0 || >=20.0.0}
     hasBin: true
 
+  cytoscape-cose-bilkent@4.1.0:
+    resolution: {integrity: sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape-fcose@2.2.0:
+    resolution: {integrity: sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==}
+    peerDependencies:
+      cytoscape: ^3.2.0
+
+  cytoscape@3.33.1:
+    resolution: {integrity: sha512-iJc4TwyANnOGR1OmWhsS9ayRS3s+XQ185FmuHObThD+5AeJCakAAbWv8KimMTt08xCCLNgneQwFp+JRJOr9qGQ==}
+    engines: {node: '>=0.10'}
+
+  d3-array@2.12.1:
+    resolution: {integrity: sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==}
+
+  d3-array@3.2.4:
+    resolution: {integrity: sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==}
+    engines: {node: '>=12'}
+
+  d3-axis@3.0.0:
+    resolution: {integrity: sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==}
+    engines: {node: '>=12'}
+
+  d3-brush@3.0.0:
+    resolution: {integrity: sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==}
+    engines: {node: '>=12'}
+
+  d3-chord@3.0.1:
+    resolution: {integrity: sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==}
+    engines: {node: '>=12'}
+
   d3-color@3.1.0:
     resolution: {integrity: sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==}
     engines: {node: '>=12'}
 
+  d3-contour@4.0.2:
+    resolution: {integrity: sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==}
+    engines: {node: '>=12'}
+
+  d3-delaunay@6.0.4:
+    resolution: {integrity: sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==}
+    engines: {node: '>=12'}
+
   d3-dispatch@3.0.1:
     resolution: {integrity: sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==}
     engines: {node: '>=12'}
@@ -6123,18 +6214,88 @@ packages:
     resolution: {integrity: sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==}
     engines: {node: '>=12'}
 
+  d3-dsv@3.0.1:
+    resolution: {integrity: sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==}
+    engines: {node: '>=12'}
+    hasBin: true
+
   d3-ease@3.0.1:
     resolution: {integrity: sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==}
     engines: {node: '>=12'}
 
+  d3-fetch@3.0.1:
+    resolution: {integrity: sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==}
+    engines: {node: '>=12'}
+
+  d3-force@3.0.0:
+    resolution: {integrity: sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==}
+    engines: {node: '>=12'}
+
+  d3-format@3.1.2:
+    resolution: {integrity: sha512-AJDdYOdnyRDV5b6ArilzCPPwc1ejkHcoyFarqlPqT7zRYjhavcT3uSrqcMvsgh2CgoPbK3RCwyHaVyxYcP2Arg==}
+    engines: {node: '>=12'}
+
+  d3-geo@3.1.1:
+    resolution: {integrity: sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==}
+    engines: {node: '>=12'}
+
+  d3-hierarchy@3.1.2:
+    resolution: {integrity: sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==}
+    engines: {node: '>=12'}
+
   d3-interpolate@3.0.1:
     resolution: {integrity: sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==}
     engines: {node: '>=12'}
 
+  d3-path@1.0.9:
+    resolution: {integrity: sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==}
+
+  d3-path@3.1.0:
+    resolution: {integrity: sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==}
+    engines: {node: '>=12'}
+
+  d3-polygon@3.0.1:
+    resolution: {integrity: sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==}
+    engines: {node: '>=12'}
+
+  d3-quadtree@3.0.1:
+    resolution: {integrity: sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==}
+    engines: {node: '>=12'}
+
+  d3-random@3.0.1:
+    resolution: {integrity: sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==}
+    engines: {node: '>=12'}
+
+  d3-sankey@0.12.3:
+    resolution: {integrity: sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==}
+
+  d3-scale-chromatic@3.1.0:
+    resolution: {integrity: sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==}
+    engines: {node: '>=12'}
+
+  d3-scale@4.0.2:
+    resolution: {integrity: sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==}
+    engines: {node: '>=12'}
+
   d3-selection@3.0.0:
     resolution: {integrity: sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==}
     engines: {node: '>=12'}
 
+  d3-shape@1.3.7:
+    resolution: {integrity: sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==}
+
+  d3-shape@3.2.0:
+    resolution: {integrity: sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==}
+    engines: {node: '>=12'}
+
+  d3-time-format@4.1.0:
+    resolution: {integrity: sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==}
+    engines: {node: '>=12'}
+
+  d3-time@3.1.0:
+    resolution: {integrity: sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==}
+    engines: {node: '>=12'}
+
   d3-timer@3.0.1:
     resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
     engines: {node: '>=12'}
@@ -6149,6 +6310,13 @@ packages:
     resolution: {integrity: sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==}
     engines: {node: '>=12'}
 
+  d3@7.9.0:
+    resolution: {integrity: sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==}
+    engines: {node: '>=12'}
+
+  dagre-d3-es@7.0.14:
+    resolution: {integrity: sha512-P4rFMVq9ESWqmOgK+dlXvOtLwYg0i7u0HBGJER0LZDJT2VHIPAMZ/riPxqJceWMStH5+E61QxFra9kIS3AqdMg==}
+
   damerau-levenshtein@1.0.8:
     resolution: {integrity: sha512-sdQSFB7+llfUcQHUQO3+B8ERRj0Oa4w9POWMI/puGtuf7gFywGmkaLCElnudfTiKZV+NvHqL0ifzdrI8Ro7ESA==}
 
@@ -6187,6 +6355,9 @@ packages:
   dayjs@1.11.13:
     resolution: {integrity: sha512-oaMBel6gjolK862uaPQOVTA7q3TZhuSvuMQAAglQDOWYO9A91IrAOUJEyKVlqJlHE0vq5p5UXxzdPfMH/x6xNg==}
 
+  dayjs@1.11.19:
+    resolution: {integrity: sha512-t5EcLVS6QPBNqM2z8fakk/NKel+Xzshgt8FFKAn+qwlD1pzZWxh0nVCrvFK7ZDb6XucZeF9z8C7CBWTRIVApAw==}
+
   debug@2.6.9:
     resolution: {integrity: sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==}
     peerDependencies:
@@ -6287,6 +6458,9 @@ packages:
     resolution: {integrity: sha512-ua8BhapfP0JUJKC/zV9yHHDW/rDoDxP4Zhn3AkA6/xT6gY7jYXJiaeyBZznYVujhZZET+UgcbZiQ7sN3WqcImg==}
     engines: {node: '>=10'}
 
+  delaunator@5.0.1:
+    resolution: {integrity: sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==}
+
   delayed-stream@1.0.0:
     resolution: {integrity: sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==}
     engines: {node: '>=0.4.0'}
@@ -6417,6 +6591,10 @@ packages:
   dompurify@3.2.3:
     resolution: {integrity: sha512-U1U5Hzc2MO0oW3DF+G9qYN0aT7atAou4AgI0XjWz061nyBPbdxkfdhfy5uMgGn6+oLFCfn44ZGbdDqCzVmlOWA==}
 
+  dompurify@3.3.2:
+    resolution: {integrity: sha512-6obghkliLdmKa56xdbLOpUZ43pAR6xFy1uOrxBaIDjT+yaRuuybLjGS9eVBoSR/UPU5fq3OXClEHLJNGvbxKpQ==}
+    engines: {node: '>=20'}
+
   domutils@1.7.0:
     resolution: {integrity: sha512-Lgd2XcJ/NjEw+7tFvfKxOzCYKZsdct5lczQ2ZaQY8Djz7pfAD3Gbp8ySJWtreII/vDlMVmxwa6pHmdxIYgttDg==}
 
@@ -7471,6 +7649,9 @@ packages:
     resolution: {integrity: sha512-ax7ZYomf6jqPTQ4+XCpUGyXKHk5WweS+e05MBO4/y3WJ5RkmPXNKvX+bx1behVILVwr6JSQvZAku021CHPXG3Q==}
     engines: {node: '>=10'}
 
+  hachure-fill@0.5.2:
+    resolution: {integrity: sha512-3GKBOn+m2LX9iq+JC1064cSFprJY4jL1jCXTcpnfER5HYE2l/4EfWSGzkPa/ZDBmYI0ZOEj5VHV/eKnPGkHuOg==}
+
   handle-thing@2.0.1:
     resolution: {integrity: sha512-9Qn4yBxelxoh2Ow62nP+Ka/kMnOXRi8BXnRaUwezLNhqelnN49xKz4F/dPP8OYLxLxq6JDtZb2i9XznUQbNPTg==}
 
@@ -7732,6 +7913,13 @@ packages:
     resolution: {integrity: sha512-4gd7VpWNQNB4UKKCFFVcp1AVv+FMOgs9NKzjHKusc8jTMhd5eL1NqQqOpE0KzMds804/yHlglp3uxgluOqAPLw==}
     engines: {node: '>= 0.4'}
 
+  internmap@1.0.1:
+    resolution: {integrity: sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==}
+
+  internmap@2.0.3:
+    resolution: {integrity: sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==}
+    engines: {node: '>=12'}
+
   invariant@2.2.4:
     resolution: {integrity: sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==}
 
@@ -8447,9 +8635,16 @@ packages:
   just-curry-it@5.3.0:
     resolution: {integrity: sha512-silMIRiFjUWlfaDhkgSzpuAyQ6EX/o09Eu8ZBfmFwQMbax7+LQzeIU2CBrICT6Ne4l86ITCGvUCBpCubWYy0Yw==}
 
+  katex@0.16.38:
+    resolution: {integrity: sha512-cjHooZUmIAUmDsHBN+1n8LaZdpmbj03LtYeYPyuYB7OuloiaeaV6N4LcfjcnHVzGWjVQmKrxxTrpDcmSzEZQwQ==}
+    hasBin: true
+
   keyv@4.5.4:
     resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
 
+  khroma@2.1.0:
+    resolution: {integrity: sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==}
+
   kind-of@3.2.2:
     resolution: {integrity: sha512-NOW9QQXMoZGg/oqnVNoNTTIFEIid1627WCffUBJEdMxYApq7mNE7CpzucIPc+ZQg25Phej7IJSmX3hO+oblOtQ==}
     engines: {node: '>=0.10.0'}
@@ -8470,6 +8665,10 @@ packages:
     resolution: {integrity: sha512-dhG34DXATL5hSxJbIexCft8FChFXtmskoZYnoPWjXQuebWYCNkVeV3KkGegCK9CP1oswI/vQibS2GY7Em/sJJA==}
     engines: {node: '>= 8'}
 
+  langium@4.2.1:
+    resolution: {integrity: sha512-zu9QWmjpzJcomzdJQAHgDVhLGq5bLosVak1KVa40NzQHXfqr4eAHupvnPOVXEoLkg6Ocefvf/93d//SB7du4YQ==}
+    engines: {node: '>=20.10.0', npm: '>=10.2.3'}
+
   language-subtag-registry@0.3.23:
     resolution: {integrity: sha512-0K65Lea881pHotoGEa5gDlMxt3pctLi2RplBb7Ezh4rRdLEOtgi7n4EwK9lamnUCkKBqaeKRVebTq6BAxSkpXQ==}
 
@@ -8480,6 +8679,12 @@ packages:
   launch-editor@2.12.0:
     resolution: {integrity: sha512-giOHXoOtifjdHqUamwKq6c49GzBdLjvxrd2D+Q4V6uOHopJv7p9VJxikDsQ/CBXZbEITgUqSVHXLTG3VhPP1Dg==}
 
+  layout-base@1.0.2:
+    resolution: {integrity: sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==}
+
+  layout-base@2.0.1:
+    resolution: {integrity: sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==}
+
   lazy-ass@1.6.0:
     resolution: {integrity: sha512-cc8oEVoctTvsFZ/Oje/kGnHbpWHYBe8IAJe4C0QNc3t8uM/0Y8+erSz/7Y1ALuXTEZTMvxXwO6YbX1ey3ujiZw==}
     engines: {node: '> 0.8'}
@@ -8571,6 +8776,9 @@ packages:
     resolution: {integrity: sha512-gvVijfZvn7R+2qyPX8mAuKcFGDf6Nc61GdvGafQsHL0sBIxfKzA+usWn4GFC/bk+QdwPUD4kWFJLhElipq+0VA==}
     engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
 
+  lodash-es@4.17.23:
+    resolution: {integrity: sha512-kVI48u3PZr38HdYz98UmfPnXl2DXrpdctLrFLCd3kOx1xUkOmpFPx7gCWWM5MPkL/fD8zb+Ph0QzjGFs4+hHWg==}
+
   lodash._reinterpolate@3.0.0:
     resolution: {integrity: sha512-xYHt68QRoYGjeeM/XOE1uJtvXQAgvszfBhjV4yvsQH0u2i9I6cI6c6/eG4Hh3UAOVn0y/xAXwmTzEay49Q//HA==}
 
@@ -8718,6 +8926,11 @@ packages:
     engines: {node: '>=0.10.0'}
     hasBin: true
 
+  marked@16.4.2:
+    resolution: {integrity: sha512-TI3V8YYWvkVf3KJe1dRkpnjs68JUPyEa5vjKrp1XEEJUAOaQc+Qj+L1qWbPd0SJuAdQkFU0h73sXXqwDYxsiDA==}
+    engines: {node: '>= 20'}
+    hasBin: true
+
   marked@4.3.0:
     resolution: {integrity: sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==}
     engines: {node: '>= 12'}
@@ -8803,6 +9016,9 @@ packages:
     resolution: {integrity: sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==}
     engines: {node: '>= 8'}
 
+  mermaid@11.13.0:
+    resolution: {integrity: sha512-fEnci+Immw6lKMFI8sqzjlATTyjLkRa6axrEgLV2yHTfv8r+h1wjFbV6xeRtd4rUV1cS4EpR9rwp3Rci7TRWDw==}
+
   methods@1.1.2:
     resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==}
     engines: {node: '>= 0.6'}
@@ -9348,6 +9564,9 @@ packages:
   package-json-from-dist@1.0.1:
     resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
 
+  package-manager-detector@1.6.0:
+    resolution: {integrity: sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA==}
+
   pako@0.2.9:
     resolution: {integrity: sha512-NUcwaKxUxWrZLpDG+z/xZaCgQITkA/Dv4V/T6bw7VON6l1Xz/VnrBqrYjZQ12TamKHzITTfOEIYUj48y2KXImA==}
 
@@ -9384,6 +9603,9 @@ packages:
   path-case@3.0.4:
     resolution: {integrity: sha512-qO4qCFjXqVTrcbPt/hQfhTQ+VhFsqNKOPtytgNKkKxSoEp3XPUQ8ObFuePylOIok5gjn69ry8XiULxCwot3Wfg==}
 
+  path-data-parser@0.1.0:
+    resolution: {integrity: sha512-NOnmBpt5Y2RWbuv0LMzsayp3lVylAHLPUTut412ZA3l+C4uw4ZVkQbjShYCQ8TCpUMdPapr4YjUqLYD6v68j+w==}
+
   path-equal@1.2.5:
     resolution: {integrity: sha512-i73IctDr3F2W+bsOWDyyVm/lqsXO47aY9nsFZUjTT/aljSbkxHxxCoyZ9UUrM8jK0JVod+An+rl48RCsvWM+9g==}
 
@@ -9502,6 +9724,12 @@ packages:
     resolution: {integrity: sha512-2Rb3vm+EXble/sMXNSu6eoBx8e79gKqhNq9F5ZWW6ERNCTE/Q0wQNne5541tE5vKjfM8hpNCYL+LGc1YTfI0dg==}
     engines: {node: '>=6'}
 
+  points-on-curve@0.2.0:
+    resolution: {integrity: sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A==}
+
+  points-on-path@0.2.1:
+    resolution: {integrity: sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g==}
+
   polished@4.3.1:
     resolution: {integrity: sha512-OBatVyC/N7SCW/FaDHrSd+vn0o5cS855TOmYi4OkdWUMSJCET/xip//ch8xGUvtr3i44X9LVyWwQlRMTN3pwSA==}
     engines: {node: '>=10'}
@@ -10529,6 +10757,9 @@ packages:
     deprecated: Rimraf versions prior to v4 are no longer supported
     hasBin: true
 
+  robust-predicates@3.0.2:
+    resolution: {integrity: sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==}
+
   rollup-plugin-terser@7.0.2:
     resolution: {integrity: sha512-w3iIaU4OxcF52UUXiZNsNeuXIMDvFrr+ZXK6bFZ0Q60qyVfq4uLptoS4bbq3paG3x216eQllFZX7zt6TIImguQ==}
     deprecated: This package has been deprecated and is no longer maintained. Please use @rollup/plugin-terser
@@ -10545,12 +10776,18 @@ packages:
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
     hasBin: true
 
+  roughjs@4.6.6:
+    resolution: {integrity: sha512-ZUz/69+SYpFN/g/lUlo2FXcIjRkSu3nDarreVdGGndHEBJ6cXPdKguS8JGxwj5HA5xIbVKSmLgr5b3AWxtRfvQ==}
+
   rrweb-cssom@0.7.1:
     resolution: {integrity: sha512-TrEMa7JGdVm0UThDJSx7ddw5nVm3UJS9o9CCIZ72B1vSyEZoziDqBYP3XIoi/12lKrJR8rE3jeFHMok2F/Mnsg==}
 
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
+  rw@1.3.3:
+    resolution: {integrity: sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==}
+
   rxjs@7.8.1:
     resolution: {integrity: sha512-AA3TVj+0A2iuIoQkWEK/tqFjBq2j+6PO6Y0zJcvzLAFhEFIO3HL0vls9hWLncZbAAbK0mar7oZ4V079I/qPMxg==}
 
@@ -11081,6 +11318,9 @@ packages:
     peerDependencies:
       postcss: ^8.2.15
 
+  stylis@4.3.6:
+    resolution: {integrity: sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==}
+
   sucrase@3.35.0:
     resolution: {integrity: sha512-8EbVDiu9iN/nESwxeSxDKe0dunta1GOlHufmSSXxMD2z2/tMZpDMpvXQGsc+ajGo8y2uYUmixaSRUc/QPoQ0GA==}
     engines: {node: '>=16 || 14 >=14.17'}
@@ -11278,6 +11518,10 @@ packages:
   tinyexec@0.3.2:
     resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
 
+  tinyexec@1.0.2:
+    resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
+    engines: {node: '>=18'}
+
   tinyglobby@0.2.15:
     resolution: {integrity: sha512-j2Zq4NyQYG5XMST4cbs02Ak8iJUdxRM0XI5QyxXuZOzKOINmWurp3smXu3y5wDcJrptwpSjgXHzIQxR0omXljQ==}
     engines: {node: '>=12.0.0'}
@@ -11775,6 +12019,10 @@ packages:
     resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
     engines: {node: '>= 0.4.0'}
 
+  uuid@11.1.0:
+    resolution: {integrity: sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==}
+    hasBin: true
+
   uuid@8.3.2:
     resolution: {integrity: sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==}
     hasBin: true
@@ -11812,15 +12060,29 @@ packages:
   vfile@5.3.7:
     resolution: {integrity: sha512-r7qlzkgErKjobAmyNIkkSpizsFPYiUPuJb5pNW1RB4JcYVZhs4lIbVqk8XPk033CV/1z8ss5pkax8SuhGpcG8g==}
 
+  vscode-jsonrpc@8.2.0:
+    resolution: {integrity: sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==}
+    engines: {node: '>=14.0.0'}
+
+  vscode-languageserver-protocol@3.17.5:
+    resolution: {integrity: sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==}
+
   vscode-languageserver-textdocument@1.0.12:
     resolution: {integrity: sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==}
 
   vscode-languageserver-types@3.17.5:
     resolution: {integrity: sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==}
 
+  vscode-languageserver@9.0.1:
+    resolution: {integrity: sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==}
+    hasBin: true
+
   vscode-uri@3.0.8:
     resolution: {integrity: sha512-AyFQ0EVmsOZOlAnxoFOGOq1SQDWAB7C6aqMGS23svWAllfOaxbuFvcT8D1i8z3Gyn8fraVeZNNmN6e9bxxXkKw==}
 
+  vscode-uri@3.1.0:
+    resolution: {integrity: sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==}
+
   w3c-hr-time@1.0.2:
     resolution: {integrity: sha512-z8P5DvDNjKDoFIHK7q8r8lackT6l+jo/Ye3HOle7l9nICP9lf1Ci25fy9vHd0JOWewkIFzXIEig3TdKT7JQ5fQ==}
     deprecated: Use your platform's native performance.now() and performance.timeOrigin.
@@ -12260,6 +12522,11 @@ snapshots:
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
 
+  '@antfu/install-pkg@1.1.0':
+    dependencies:
+      package-manager-detector: 1.6.0
+      tinyexec: 1.0.2
+
   '@apideck/better-ajv-errors@0.3.6(ajv@8.17.1)':
     dependencies:
       ajv: 8.17.1
@@ -15401,6 +15668,8 @@ snapshots:
 
   '@bcoe/v8-coverage@0.2.3': {}
 
+  '@braintree/sanitize-url@7.1.2': {}
+
   '@changesets/apply-release-plan@6.1.4':
     dependencies:
       '@babel/runtime': 7.28.6
@@ -15550,6 +15819,23 @@ snapshots:
       human-id: 1.0.2
       prettier: 2.8.8
 
+  '@chevrotain/cst-dts-gen@11.1.2':
+    dependencies:
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
+  '@chevrotain/gast@11.1.2':
+    dependencies:
+      '@chevrotain/types': 11.1.2
+      lodash-es: 4.17.23
+
+  '@chevrotain/regexp-to-ast@11.1.2': {}
+
+  '@chevrotain/types@11.1.2': {}
+
+  '@chevrotain/utils@11.1.2': {}
+
   '@codemirror/autocomplete@6.18.1(@codemirror/language@6.10.3)(@codemirror/state@6.4.1)(@codemirror/view@6.26.3)(@lezer/common@1.2.1)':
     dependencies:
       '@codemirror/language': 6.10.3
@@ -15999,6 +16285,14 @@ snapshots:
     dependencies:
       just-curry-it: 3.2.1
 
+  '@iconify/types@2.0.0': {}
+
+  '@iconify/utils@3.1.0':
+    dependencies:
+      '@antfu/install-pkg': 1.1.0
+      '@iconify/types': 2.0.0
+      mlly: 1.8.0
+
   '@isaacs/cliui@8.0.2':
     dependencies:
       string-width: 5.1.2
@@ -16319,6 +16613,10 @@ snapshots:
       '@types/react': 18.2.18
       react: 18.2.0
 
+  '@mermaid-js/parser@1.0.1':
+    dependencies:
+      langium: 4.2.1
+
   '@monaco-editor/loader@1.4.0(monaco-editor@0.34.1)':
     dependencies:
       monaco-editor: 0.34.1
@@ -19395,6 +19693,11 @@ snapshots:
 
   '@ungap/structured-clone@1.3.0': {}
 
+  '@upsetjs/venn.js@2.0.0':
+    optionalDependencies:
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
   '@vitest/expect@0.34.7':
     dependencies:
       '@vitest/spy': 0.34.7
@@ -20454,6 +20757,20 @@ snapshots:
 
   check-types@11.2.3: {}
 
+  chevrotain-allstar@0.3.1(chevrotain@11.1.2):
+    dependencies:
+      chevrotain: 11.1.2
+      lodash-es: 4.17.23
+
+  chevrotain@11.1.2:
+    dependencies:
+      '@chevrotain/cst-dts-gen': 11.1.2
+      '@chevrotain/gast': 11.1.2
+      '@chevrotain/regexp-to-ast': 11.1.2
+      '@chevrotain/types': 11.1.2
+      '@chevrotain/utils': 11.1.2
+      lodash-es: 4.17.23
+
   chokidar@3.6.0:
     dependencies:
       anymatch: 3.1.3
@@ -20709,6 +21026,14 @@ snapshots:
 
   core-util-is@1.0.3: {}
 
+  cose-base@1.0.3:
+    dependencies:
+      layout-base: 1.0.2
+
+  cose-base@2.2.0:
+    dependencies:
+      layout-base: 2.0.1
+
   cosmiconfig@6.0.0:
     dependencies:
       '@types/parse-json': 4.0.2
@@ -20962,8 +21287,50 @@ snapshots:
       untildify: 4.0.0
       yauzl: 2.10.0
 
+  cytoscape-cose-bilkent@4.1.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 1.0.3
+      cytoscape: 3.33.1
+
+  cytoscape-fcose@2.2.0(cytoscape@3.33.1):
+    dependencies:
+      cose-base: 2.2.0
+      cytoscape: 3.33.1
+
+  cytoscape@3.33.1: {}
+
+  d3-array@2.12.1:
+    dependencies:
+      internmap: 1.0.1
+
+  d3-array@3.2.4:
+    dependencies:
+      internmap: 2.0.3
+
+  d3-axis@3.0.0: {}
+
+  d3-brush@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-interpolate: 3.0.1
+      d3-selection: 3.0.0
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+
+  d3-chord@3.0.1:
+    dependencies:
+      d3-path: 3.1.0
+
   d3-color@3.1.0: {}
 
+  d3-contour@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-delaunay@6.0.4:
+    dependencies:
+      delaunator: 5.0.1
+
   d3-dispatch@3.0.1: {}
 
   d3-drag@3.0.0:
@@ -20971,14 +21338,82 @@ snapshots:
       d3-dispatch: 3.0.1
       d3-selection: 3.0.0
 
+  d3-dsv@3.0.1:
+    dependencies:
+      commander: 7.2.0
+      iconv-lite: 0.6.3
+      rw: 1.3.3
+
   d3-ease@3.0.1: {}
 
+  d3-fetch@3.0.1:
+    dependencies:
+      d3-dsv: 3.0.1
+
+  d3-force@3.0.0:
+    dependencies:
+      d3-dispatch: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-timer: 3.0.1
+
+  d3-format@3.1.2: {}
+
+  d3-geo@3.1.1:
+    dependencies:
+      d3-array: 3.2.4
+
+  d3-hierarchy@3.1.2: {}
+
   d3-interpolate@3.0.1:
     dependencies:
       d3-color: 3.1.0
 
+  d3-path@1.0.9: {}
+
+  d3-path@3.1.0: {}
+
+  d3-polygon@3.0.1: {}
+
+  d3-quadtree@3.0.1: {}
+
+  d3-random@3.0.1: {}
+
+  d3-sankey@0.12.3:
+    dependencies:
+      d3-array: 2.12.1
+      d3-shape: 1.3.7
+
+  d3-scale-chromatic@3.1.0:
+    dependencies:
+      d3-color: 3.1.0
+      d3-interpolate: 3.0.1
+
+  d3-scale@4.0.2:
+    dependencies:
+      d3-array: 3.2.4
+      d3-format: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+
   d3-selection@3.0.0: {}
 
+  d3-shape@1.3.7:
+    dependencies:
+      d3-path: 1.0.9
+
+  d3-shape@3.2.0:
+    dependencies:
+      d3-path: 3.1.0
+
+  d3-time-format@4.1.0:
+    dependencies:
+      d3-time: 3.1.0
+
+  d3-time@3.1.0:
+    dependencies:
+      d3-array: 3.2.4
+
   d3-timer@3.0.1: {}
 
   d3-transition@3.0.1(d3-selection@3.0.0):
@@ -20998,6 +21433,44 @@ snapshots:
       d3-selection: 3.0.0
       d3-transition: 3.0.1(d3-selection@3.0.0)
 
+  d3@7.9.0:
+    dependencies:
+      d3-array: 3.2.4
+      d3-axis: 3.0.0
+      d3-brush: 3.0.0
+      d3-chord: 3.0.1
+      d3-color: 3.1.0
+      d3-contour: 4.0.2
+      d3-delaunay: 6.0.4
+      d3-dispatch: 3.0.1
+      d3-drag: 3.0.0
+      d3-dsv: 3.0.1
+      d3-ease: 3.0.1
+      d3-fetch: 3.0.1
+      d3-force: 3.0.0
+      d3-format: 3.1.2
+      d3-geo: 3.1.1
+      d3-hierarchy: 3.1.2
+      d3-interpolate: 3.0.1
+      d3-path: 3.1.0
+      d3-polygon: 3.0.1
+      d3-quadtree: 3.0.1
+      d3-random: 3.0.1
+      d3-scale: 4.0.2
+      d3-scale-chromatic: 3.1.0
+      d3-selection: 3.0.0
+      d3-shape: 3.2.0
+      d3-time: 3.1.0
+      d3-time-format: 4.1.0
+      d3-timer: 3.0.1
+      d3-transition: 3.0.1(d3-selection@3.0.0)
+      d3-zoom: 3.0.0
+
+  dagre-d3-es@7.0.14:
+    dependencies:
+      d3: 7.9.0
+      lodash-es: 4.17.23
+
   damerau-levenshtein@1.0.8: {}
 
   dashdash@1.14.1:
@@ -21041,6 +21514,8 @@ snapshots:
 
   dayjs@1.11.13: {}
 
+  dayjs@1.11.19: {}
+
   debug@2.6.9:
     dependencies:
       ms: 2.0.0
@@ -21153,6 +21628,10 @@ snapshots:
       rimraf: 3.0.2
       slash: 3.0.0
 
+  delaunator@5.0.1:
+    dependencies:
+      robust-predicates: 3.0.2
+
   delayed-stream@1.0.0: {}
 
   depd@1.1.2: {}
@@ -21258,6 +21737,10 @@ snapshots:
     optionalDependencies:
       '@types/trusted-types': 2.0.7
 
+  dompurify@3.3.2:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
   domutils@1.7.0:
     dependencies:
       dom-serializer: 0.2.2
@@ -22808,6 +23291,8 @@ snapshots:
     dependencies:
       duplexer: 0.1.2
 
+  hachure-fill@0.5.2: {}
+
   handle-thing@2.0.1: {}
 
   handlebars@4.7.8:
@@ -23080,6 +23565,10 @@ snapshots:
       hasown: 2.0.2
       side-channel: 1.1.0
 
+  internmap@1.0.1: {}
+
+  internmap@2.0.3: {}
+
   invariant@2.2.4:
     dependencies:
       loose-envify: 1.4.0
@@ -24096,10 +24585,16 @@ snapshots:
 
   just-curry-it@5.3.0: {}
 
+  katex@0.16.38:
+    dependencies:
+      commander: 8.3.0
+
   keyv@4.5.4:
     dependencies:
       json-buffer: 3.0.1
 
+  khroma@2.1.0: {}
+
   kind-of@3.2.2:
     dependencies:
       is-buffer: 1.1.6
@@ -24112,6 +24607,14 @@ snapshots:
 
   klona@2.0.6: {}
 
+  langium@4.2.1:
+    dependencies:
+      chevrotain: 11.1.2
+      chevrotain-allstar: 0.3.1(chevrotain@11.1.2)
+      vscode-languageserver: 9.0.1
+      vscode-languageserver-textdocument: 1.0.12
+      vscode-uri: 3.1.0
+
   language-subtag-registry@0.3.23: {}
 
   language-tags@1.0.9:
@@ -24123,6 +24626,10 @@ snapshots:
       picocolors: 1.1.1
       shell-quote: 1.8.3
 
+  layout-base@1.0.2: {}
+
+  layout-base@2.0.1: {}
+
   lazy-ass@1.6.0: {}
 
   lazy-cache@2.0.2:
@@ -24216,6 +24723,8 @@ snapshots:
     dependencies:
       p-locate: 6.0.0
 
+  lodash-es@4.17.23: {}
+
   lodash._reinterpolate@3.0.0: {}
 
   lodash.castarray@4.4.0: {}
@@ -24360,6 +24869,8 @@ snapshots:
       repeat-string: 1.6.1
       strip-color: 0.1.0
 
+  marked@16.4.2: {}
+
   marked@4.3.0: {}
 
   math-intrinsics@1.1.0: {}
@@ -24496,6 +25007,30 @@ snapshots:
 
   merge2@1.4.1: {}
 
+  mermaid@11.13.0:
+    dependencies:
+      '@braintree/sanitize-url': 7.1.2
+      '@iconify/utils': 3.1.0
+      '@mermaid-js/parser': 1.0.1
+      '@types/d3': 7.4.3
+      '@upsetjs/venn.js': 2.0.0
+      cytoscape: 3.33.1
+      cytoscape-cose-bilkent: 4.1.0(cytoscape@3.33.1)
+      cytoscape-fcose: 2.2.0(cytoscape@3.33.1)
+      d3: 7.9.0
+      d3-sankey: 0.12.3
+      dagre-d3-es: 7.0.14
+      dayjs: 1.11.19
+      dompurify: 3.3.2
+      katex: 0.16.38
+      khroma: 2.1.0
+      lodash-es: 4.17.23
+      marked: 16.4.2
+      roughjs: 4.6.6
+      stylis: 4.3.6
+      ts-dedent: 2.2.0
+      uuid: 11.1.0
+
   methods@1.1.2: {}
 
   micromark-core-commonmark@1.1.0:
@@ -25153,6 +25688,8 @@ snapshots:
 
   package-json-from-dist@1.0.1: {}
 
+  package-manager-detector@1.6.0: {}
+
   pako@0.2.9: {}
 
   pako@1.0.11: {}
@@ -25193,6 +25730,8 @@ snapshots:
       dot-case: 3.0.4
       tslib: 2.8.1
 
+  path-data-parser@0.1.0: {}
+
   path-equal@1.2.5: {}
 
   path-exists@3.0.0: {}
@@ -25287,6 +25826,13 @@ snapshots:
     transitivePeerDependencies:
       - typescript
 
+  points-on-curve@0.2.0: {}
+
+  points-on-path@0.2.1:
+    dependencies:
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+
   polished@4.3.1:
     dependencies:
       '@babel/runtime': 7.28.6
@@ -26539,6 +27085,8 @@ snapshots:
     dependencies:
       glob: 7.2.3
 
+  robust-predicates@3.0.2: {}
+
   rollup-plugin-terser@7.0.2(rollup@2.79.2):
     dependencies:
       '@babel/code-frame': 7.29.0
@@ -26573,12 +27121,21 @@ snapshots:
       '@rollup/rollup-win32-x64-msvc': 4.23.0
       fsevents: 2.3.3
 
+  roughjs@4.6.6:
+    dependencies:
+      hachure-fill: 0.5.2
+      path-data-parser: 0.1.0
+      points-on-curve: 0.2.0
+      points-on-path: 0.2.1
+
   rrweb-cssom@0.7.1: {}
 
   run-parallel@1.2.0:
     dependencies:
       queue-microtask: 1.2.3
 
+  rw@1.3.3: {}
+
   rxjs@7.8.1:
     dependencies:
       tslib: 2.8.1
@@ -27213,6 +27770,8 @@ snapshots:
       postcss: 8.4.31
       postcss-selector-parser: 6.1.2
 
+  stylis@4.3.6: {}
+
   sucrase@3.35.0:
     dependencies:
       '@jridgewell/gen-mapping': 0.3.13
@@ -27563,6 +28122,8 @@ snapshots:
 
   tinyexec@0.3.2: {}
 
+  tinyexec@1.0.2: {}
+
   tinyglobby@0.2.15:
     dependencies:
       fdir: 6.5.0(picomatch@4.0.3)
@@ -28154,6 +28715,8 @@ snapshots:
 
   utils-merge@1.0.1: {}
 
+  uuid@11.1.0: {}
+
   uuid@8.3.2: {}
 
   uuid@9.0.1: {}
@@ -28198,12 +28761,25 @@ snapshots:
       unist-util-stringify-position: 3.0.3
       vfile-message: 3.1.4
 
+  vscode-jsonrpc@8.2.0: {}
+
+  vscode-languageserver-protocol@3.17.5:
+    dependencies:
+      vscode-jsonrpc: 8.2.0
+      vscode-languageserver-types: 3.17.5
+
   vscode-languageserver-textdocument@1.0.12: {}
 
   vscode-languageserver-types@3.17.5: {}
 
+  vscode-languageserver@9.0.1:
+    dependencies:
+      vscode-languageserver-protocol: 3.17.5
+
   vscode-uri@3.0.8: {}
 
+  vscode-uri@3.1.0: {}
+
   w3c-hr-time@1.0.2:
     dependencies:
       browser-process-hrtime: 1.0.0

From f1d135503873fd02dd20c553da1cf5bd27e5ab69 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 07:54:00 +0100
Subject: [PATCH 18/23] docs reflect new functionality

---
 README.md                                     | 52 +++++++++++++++++++
 .../src/components/Modals/RedirectedModal.tsx |  5 ++
 2 files changed, 57 insertions(+)

diff --git a/README.md b/README.md
index 3bae674b8..c4e941ff0 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,58 @@ pnpm run build:ds
 pnpm run build
 ```
 
+## Features
+
+### Remote URL Import with Relative References
+
+Studio supports importing AsyncAPI files from remote URLs with automatic resolution of relative `$ref` references:
+
+- Import files from any URL (e.g., GitHub raw URLs, public APIs)
+- The parser automatically resolves relative references using the remote URL as base path
+- Example: A file at `https://example.com/specs/api.yaml` referencing `../schemas/user.json` resolves to `https://example.com/schemas/user.json`
+
+### Local Folder Access for Reference Resolution
+
+Studio can resolve local file references (e.g., `$ref: './schema.avsc'`) by requesting folder access:
+
+**Workflow:**
+1. Click **Import** → **Open Folder**
+2. Select the root folder containing your AsyncAPI files and schemas
+3. Select the main AsyncAPI file within that folder
+4. The parser automatically resolves all relative file references
+
+**Supported reference formats:**
+- `./schema.avsc` - Same directory as the AsyncAPI file
+- `../common/types.yaml` - Parent directory
+- `apis/avro/schema.avsc` - Subdirectory path
+
+**Supported schema formats:**
+- Avro `.avsc` files
+- JSON Schema `.json` files
+- YAML schema `.yaml` files
+
+**Browser compatibility:**
+- ✅ Chrome, Edge, Brave (File System Access API supported)
+- ❌ Firefox, Safari (not supported)
+
+**Security note:** Folder access is granted per session only and is not persisted. You must grant access each time you open the application.
+
+### Schema Editing
+
+- Edit both the main AsyncAPI document and referenced schema files
+- Changes to referenced schemas are automatically reflected when the parser re-validates
+- Real-time validation across all files
+
+### File Saving
+
+- Files opened from a folder (using **Open Folder**) can be saved to their original location with the **Save** button
+- For other files, the **Save** button behaves as **Save As**, allowing you to export the current editor content to a selected local file
+
+### Additional Viewers
+
+- **Markdown Preview**: View documentation files with full Markdown rendering, including Mermaid diagrams
+- **Avro Schema Viewer**: Visualize Avro schemas with automatically generated Mermaid diagrams
+
 ## Architecture decision records
 
 ### Create a new architecture decision record
diff --git a/apps/studio/src/components/Modals/RedirectedModal.tsx b/apps/studio/src/components/Modals/RedirectedModal.tsx
index aa884df39..98db2eaff 100644
--- a/apps/studio/src/components/Modals/RedirectedModal.tsx
+++ b/apps/studio/src/components/Modals/RedirectedModal.tsx
@@ -10,6 +10,11 @@ Below are the changes compared to the old AsyncAPI Playground:
 - Markdown files now have preview support, including Mermaid code blocks.
 - Studio supports the same query parameters except **template**.
 - To download an AsyncAPI document from an external source use the editor menu and select **Import from URL**. There is also an option to use a local file, base64 saved file, convert a given version of AsyncAPI document to a newer one as well as change the format from YAML to JSON and vice versa. There is also option to download AsyncAPI document as file.
+- **Local Folder Access**: Grant folder access to resolve local file references (e.g., \`./schema.avsc\`, \`../common/types.yaml\`). Use **Import** → **Open Folder** to select your project root.
+- **Schema Editing**: Edit referenced schema files directly. Changes are automatically reflected in validation.
+- **File Saving**: Files opened from folders can be saved to their original location. Other files use **Save As**.
+- **Markdown Preview**: View documentation files with full Markdown rendering, including Mermaid diagrams.
+- **Avro Schema Viewer**: Visualize Avro schemas with automatically generated Mermaid diagrams.
 - To generate the template, please click on the **Generate code/docs** item in the menu at the top right corner of the editor, enter (needed) the parameters and click **Generate**.
 - The left navigation is used to open/close the panels.
 - Errors in the AsyncAPI document are shown in a panel at the bottom of the editor. The panel is expandable.

From 76593632ba9a16055ac186fc461e008d349a7ea4 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 08:10:19 +0100
Subject: [PATCH 19/23] fix side bar and "unsaved changes" label

---
 apps/studio/src/components/Content.tsx         |  4 +---
 apps/studio/src/components/Sidebar.tsx         | 15 ++-------------
 .../src/components/Terminal/TerminalInfo.tsx   | 18 ++++++++++--------
 3 files changed, 13 insertions(+), 24 deletions(-)

diff --git a/apps/studio/src/components/Content.tsx b/apps/studio/src/components/Content.tsx
index 1db21e8f9..8bfba0930 100644
--- a/apps/studio/src/components/Content.tsx
+++ b/apps/studio/src/components/Content.tsx
@@ -3,7 +3,6 @@ import { Editor } from './Editor/Editor';
 import { Navigation } from './Navigation';
 import { Navigationv3 } from './Navigationv3';
 import { Template } from './Template';
-import { AvroPreview } from './Template/AvroPreview';
 import { VisualiserTemplate } from './Visualiser';
 
 import { debounce } from '@/helpers';
@@ -20,7 +19,7 @@ export const Content: FunctionComponent<ContentProps> = () => { // eslint-disabl
   const navigationEnabled = show.primarySidebar;
   const editorEnabled = show.primaryPanel;
   const viewEnabled = show.secondaryPanel;
-  const viewType = secondaryPanelType;
+  const viewType = secondaryPanelType === 'avro' ? 'template' : secondaryPanelType;
 
   const splitPosLeft = 'splitPos:left';
   const splitPosRight = 'splitPos:right';
@@ -71,7 +70,6 @@ export const Content: FunctionComponent<ContentProps> = () => { // eslint-disabl
         >
           {navigationAndEditor}
           {viewType === 'template' && <Template />}
-          {viewType === 'avro' && <AvroPreview />}
           {viewType === 'visualiser' && <VisualiserTemplate />}
         </SplitPane> 
       </div>
diff --git a/apps/studio/src/components/Sidebar.tsx b/apps/studio/src/components/Sidebar.tsx
index 876a95bb4..9d4f7d88f 100644
--- a/apps/studio/src/components/Sidebar.tsx
+++ b/apps/studio/src/components/Sidebar.tsx
@@ -88,24 +88,13 @@ export const Sidebar: FunctionComponent<SidebarProps> = () => {
     {
       name: 'template',
       title: 'Template preview',
-      isActive: show.secondaryPanel && secondaryPanelType === 'template',
+      isActive: show.secondaryPanel && (secondaryPanelType === 'template' || secondaryPanelType === 'avro'),
       onClick: () => updateState('secondaryPanel', 'template'),
       icon: <VscOpenPreview className="w-5 h-5" />,
       tooltip: 'Template preview',
       enabled: true,
       dataTest: 'button-template-preview',
     },
-    // avro preview
-    {
-      name: 'avro',
-      title: 'Avro preview',
-      isActive: show.secondaryPanel && secondaryPanelType === 'avro',
-      onClick: () => updateState('secondaryPanel', 'avro'),
-      icon: <VscGraph className="w-5 h-5" />,
-      tooltip: 'Avro preview',
-      enabled: true,
-      dataTest: 'button-avro-preview',
-    },
     // visuliser
     {
       name: 'visualiser',
@@ -114,7 +103,7 @@ export const Sidebar: FunctionComponent<SidebarProps> = () => {
       onClick: () => updateState('secondaryPanel', 'visualiser'),
       icon: <VscGraph className="w-5 h-5" />,
       tooltip: 'Blocks visualiser',
-      enabled: !isV3,
+      enabled: true, // !isV3, this is already compatible with v3
       dataTest: 'button-blocks-visualiser',
     },
     // newFile
diff --git a/apps/studio/src/components/Terminal/TerminalInfo.tsx b/apps/studio/src/components/Terminal/TerminalInfo.tsx
index 446bbf4c3..7148d1fa9 100644
--- a/apps/studio/src/components/Terminal/TerminalInfo.tsx
+++ b/apps/studio/src/components/Terminal/TerminalInfo.tsx
@@ -75,14 +75,16 @@ export const TerminalInfo: FunctionComponent<TerminalInfoProps> = () => {
           <span>Valid</span>
         </div>
       )}
-      <div className="ml-3">
-        <span className={file.modified ? 'text-yellow-500' : 'text-green-500'}>
-          <svg xmlns="http://www.w3.org/2000/svg" className="inline-block h-5 w-5 mr-1 -mt-0.5" viewBox="0 0 20 20" fill="currentColor">
-            <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
-          </svg>
-        </span>
-        <span>{file.modified ? 'Modified' : 'Unchanged'}</span>
-      </div>
+      {file.modified && (
+        <div className="ml-3">
+          <span className="text-yellow-500">
+            <svg xmlns="http://www.w3.org/2000/svg" className="inline-block h-5 w-5 mr-1 -mt-0.5" viewBox="0 0 20 20" fill="currentColor">
+              <path fillRule="evenodd" d="M18 10a8 8 0 11-16 0 8 8 0 0116 0zm-7 4a1 1 0 11-2 0 1 1 0 012 0zm-1-9a1 1 0 00-1 1v4a1 1 0 102 0V6a1 1 0 00-1-1z" clipRule="evenodd" />
+            </svg>
+          </span>
+          <span>Unsaved changes</span>
+        </div>
+      )}
       {actualVersion !== latestVersion && document.valid === true && (
         <div className="ml-3" 
           onClick={onNonLatestClick}

From 3b12869ef7d3eca61c9c733d0ca58c32f2e9f508 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 08:18:55 +0100
Subject: [PATCH 20/23] fixes for netlify linter

---
 apps/studio/src/components/Sidebar.tsx | 17 ++---------------
 1 file changed, 2 insertions(+), 15 deletions(-)

diff --git a/apps/studio/src/components/Sidebar.tsx b/apps/studio/src/components/Sidebar.tsx
index 9d4f7d88f..73e00bc9c 100644
--- a/apps/studio/src/components/Sidebar.tsx
+++ b/apps/studio/src/components/Sidebar.tsx
@@ -4,9 +4,9 @@ import { show as showModal } from '@ebay/nice-modal-react';
 import { Tooltip } from './common';
 import { SettingsModal, ConfirmNewFileModal } from './Modals';
 
-import { usePanelsState, panelsState, useDocumentsState } from '@/state';
+import { usePanelsState, panelsState } from '@/state';
 
-import { useEffect, useState, type FunctionComponent, type ReactNode } from 'react';
+import { type FunctionComponent, type ReactNode } from 'react';
 import type { PanelsState } from '@/state/panels.state';
 import { driverObj } from '@/helpers/driver';
 
@@ -54,12 +54,6 @@ interface SidebarProps {}
 
 export const Sidebar: FunctionComponent<SidebarProps> = () => {
   const { show, secondaryPanelType } = usePanelsState();
-  const [document, hasErrors] = useDocumentsState((state) => [
-    state.documents['asyncapi']?.document,
-    state.documents['asyncapi']?.diagnostics?.errors.length > 0,
-  ]) || [null, false];
-
-  const [isV3, setIsV3] = useState(document?.version().startsWith('3.'));
 
   let navigation: NavItem[] = [
     // navigation
@@ -126,13 +120,6 @@ export const Sidebar: FunctionComponent<SidebarProps> = () => {
     driverObj.drive(parseInt(getCurrentTourStep ?? '0', 10));
   };
 
-  useEffect(() => {
-    // if the document has no errors then only update the setIsV3 variable
-    if (!hasErrors) {
-      setIsV3(document?.version().startsWith('3.'));
-    }
-  }, [document]);
-
   if (show.activityBar === false) {
     return null;
   }

From 27bff3c6e6c0d3268beb0a5b9db226999e1164da Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 08:29:25 +0100
Subject: [PATCH 21/23] fixes for netlify linter

---
 apps/studio/src/components/Template/avro-diagram.ts | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/apps/studio/src/components/Template/avro-diagram.ts b/apps/studio/src/components/Template/avro-diagram.ts
index c20e36a91..cdef03a97 100644
--- a/apps/studio/src/components/Template/avro-diagram.ts
+++ b/apps/studio/src/components/Template/avro-diagram.ts
@@ -335,7 +335,8 @@ function findReferenceFile(
 
 function ensurePlaceholdersForReferences(entities: Map<string, AvroEntity>): void {
   const references = new Set<string>();
-  for (const entity of entities.values()) {
+  const entityList = Array.from(entities.values());
+  for (const entity of entityList) {
     for (const field of entity.fields) {
       for (const ref of field.references) {
         references.add(ref);
@@ -343,7 +344,8 @@ function ensurePlaceholdersForReferences(entities: Map<string, AvroEntity>): voi
     }
   }
 
-  for (const ref of references) {
+  const referenceList = Array.from(references);
+  for (const ref of referenceList) {
     if (!entities.has(ref)) {
       const { namespace } = getTypeNameAndNamespace(ref);
       entities.set(ref, {
@@ -368,7 +370,8 @@ function resolveExternalReferences(
   const queued = new Set<string>();
 
   const enqueueMissingRefs = () => {
-    for (const entity of entities.values()) {
+    const entityList = Array.from(entities.values());
+    for (const entity of entityList) {
       for (const field of entity.fields) {
         for (const ref of field.references) {
           if (!entities.has(ref) && !queued.has(ref)) {

From eb7fd79885441839cba38986939830564fd3eb17 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 09:01:32 +0100
Subject: [PATCH 22/23] BrowserNotSupportedModal

---
 .../Modals/BrowserNotSupportedModal.tsx       | 46 +++++++++++
 .../src/components/Modals/OpenFolderModal.tsx |  8 +-
 apps/studio/src/components/Modals/index.tsx   |  3 +-
 apps/studio/src/services/editor.service.tsx   | 82 +++++++++++--------
 .../src/types/window-file-system-access.d.ts  |  6 ++
 5 files changed, 110 insertions(+), 35 deletions(-)
 create mode 100644 apps/studio/src/components/Modals/BrowserNotSupportedModal.tsx

diff --git a/apps/studio/src/components/Modals/BrowserNotSupportedModal.tsx b/apps/studio/src/components/Modals/BrowserNotSupportedModal.tsx
new file mode 100644
index 000000000..014da6489
--- /dev/null
+++ b/apps/studio/src/components/Modals/BrowserNotSupportedModal.tsx
@@ -0,0 +1,46 @@
+import { create } from '@ebay/nice-modal-react';
+
+import { ConfirmModal } from './ConfirmModal';
+
+interface BrowserNotSupportedModalProps {
+  isBrave?: boolean;
+}
+
+export const BrowserNotSupportedModal = create<BrowserNotSupportedModalProps>(({ isBrave = false }) => {
+  return (
+    <ConfirmModal
+      title="File System Access API Not Supported on this Browser"
+      cancelText="Close"
+      containerClassName="w-full max-w-2xl sm:w-3/5"
+    >
+      <div className="flex flex-col space-y-4 text-sm text-gray-700">
+        <p>
+          The Open Folder feature requires the File System Access API, which is not available in your current browser context.
+        </p>
+        <div>
+          <p className="font-medium text-gray-900">Browser support</p>
+          <ul className="mt-2 space-y-1">
+            <li>✅ Chrome</li>
+            <li>✅ Edge</li>
+            <li>✅ Brave (requires manual flag enablement)</li>
+            <li>❌ Firefox (not supported)</li>
+            <li>❌ Safari (not supported)</li>
+          </ul>
+        </div>
+        {isBrave && (
+          <div className="rounded-md border border-yellow-200 bg-yellow-50 p-4">
+            <p className="font-medium text-gray-900">You are using Brave browser. To enable this feature:</p>
+            <ol className="mt-2 list-decimal space-y-1 pl-5">
+              <li>
+                Navigate to <code className="rounded bg-white px-1 py-0.5 text-pink-600">brave://flags/#file-system-access-api</code>
+              </li>
+              <li>Enable the &quot;File System Access API&quot; flag</li>
+              <li>Restart Brave browser</li>
+              <li>Try again</li>
+            </ol>
+          </div>
+        )}
+      </div>
+    </ConfirmModal>
+  );
+});
diff --git a/apps/studio/src/components/Modals/OpenFolderModal.tsx b/apps/studio/src/components/Modals/OpenFolderModal.tsx
index fd7c5f016..79a1b8e52 100644
--- a/apps/studio/src/components/Modals/OpenFolderModal.tsx
+++ b/apps/studio/src/components/Modals/OpenFolderModal.tsx
@@ -13,8 +13,12 @@ export const OpenFolderModal = create(() => {
     console.log('[DEBUG:ui] Open Folder — Continue clicked');
     toast.loading('Granting folder access...', { id: toastId });
     try {
-      await editorSvc.grantFolderAccess();
-      toast.success('Folder access granted! File references will now be resolved.', { id: toastId });
+      const granted = await editorSvc.grantFolderAccess();
+      if (granted) {
+        toast.success('Folder access granted! File references will now be resolved.', { id: toastId });
+      } else {
+        toast.dismiss(toastId);
+      }
     } catch (err: unknown) {
       console.error('[DEBUG:ui] Open Folder failed', err);
       const message = err instanceof Error ? err.message : 'Unknown error';
diff --git a/apps/studio/src/components/Modals/index.tsx b/apps/studio/src/components/Modals/index.tsx
index 750b2fc3e..96a154517 100644
--- a/apps/studio/src/components/Modals/index.tsx
+++ b/apps/studio/src/components/Modals/index.tsx
@@ -1,6 +1,7 @@
 export * from './Generator/GeneratorModal';
 export * from './Settings/SettingsModal';
 
+export * from './BrowserNotSupportedModal';
 export * from './ConfirmModal';
 export * from './ConvertModal';
 export * from './ConvertToLatestModal';
@@ -11,4 +12,4 @@ export * from './ImportUUIDModal';
 export * from './NewFileModal';
 export * from './OpenFolderModal';
 export * from './RedirectedModal';
-export * from './ConfirmNewFileModal';
\ No newline at end of file
+export * from './ConfirmNewFileModal';
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 9ce03cecf..523da20a7 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -1,12 +1,14 @@
-import { AbstractService } from './abstract.service';
-
+import { AbstractService } from './abstract.service';
+
 import { KeyMod, KeyCode } from 'monaco-editor/esm/vs/editor/editor.api';
 import { DiagnosticSeverity } from '@asyncapi/parser';
+import { show } from '@ebay/nice-modal-react';
 import { Range, MarkerSeverity } from 'monaco-editor/esm/vs/editor/editor.api';
 import toast from 'react-hot-toast';
 
+import { BrowserNotSupportedModal } from '@/components/Modals';
 import { appState, documentsState, filesState } from '@/state';
-import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
+import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
 
 import type * as monacoAPI from 'monaco-editor/esm/vs/editor/editor.api';
 import type { Diagnostic } from '@asyncapi/parser';
@@ -265,25 +267,28 @@ export class EditorService extends AbstractService {
     this.updateState({ content: converted, updateModel: true });
   }
 
-  async grantFolderAccess(): Promise<void> {
-    const folderAccessToastId = 'folder-access';
-    if (!window.isSecureContext) {
-      throw new Error('Open Folder requires a secure context (HTTPS or localhost).');
-    }
-    if (
-      typeof window.showDirectoryPicker !== 'function' ||
-      typeof window.showOpenFilePicker !== 'function'
-    ) {
-      throw new Error('This browser context does not support the File System Access API.');
-    }
+  async grantFolderAccess(): Promise<boolean> {
+    const folderAccessToastId = 'folder-access';
+    if (!window.isSecureContext) {
+      throw new Error('Open Folder requires a secure context (HTTPS or localhost).');
+    }
+    if (
+      typeof window.showDirectoryPicker !== 'function' ||
+      typeof window.showOpenFilePicker !== 'function'
+    ) {
+      show(BrowserNotSupportedModal, {
+        isBrave: await this.isBraveBrowser(),
+      });
+      return false;
+    }
     let directoryHandle: DirectoryHandle;
-    try {
-      directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
-    } catch (err: any) {
-      if (err?.name === 'AbortError') return;
-      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
-      throw err;
-    }
+    try {
+      directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
+    } catch (err: any) {
+      if (err?.name === 'AbortError') return false;
+      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
+      throw err;
+    }
 
     toast.loading('Please select the AsyncAPI file within the folder...', { id: folderAccessToastId });
     let fileHandle: FileHandle;
@@ -293,19 +298,19 @@ export class EditorService extends AbstractService {
         multiple: false,
       });
       fileHandle = handle;
-    } catch (err: any) {
-      toast.dismiss(folderAccessToastId);
-      if (err?.name === 'AbortError') return;
-      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
-      throw err;
-    }
+    } catch (err: any) {
+      toast.dismiss(folderAccessToastId);
+      if (err?.name === 'AbortError') return false;
+      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
+      throw err;
+    }
 
     const pathParts = await directoryHandle.resolve(fileHandle);
-    if (!pathParts) {
-      toast.dismiss(folderAccessToastId);
-      toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
-      return;
-    }
+    if (!pathParts) {
+      toast.dismiss(folderAccessToastId);
+      toast.error('Selected file is not within the chosen folder. Please select a file inside the folder.');
+      return false;
+    }
 
     const localPath = pathParts.join('/');
     const files = await this.collectLocalProjectFiles(directoryHandle);
@@ -342,6 +347,19 @@ export class EditorService extends AbstractService {
     });
 
     toast.dismiss(folderAccessToastId);
+    return true;
+  }
+
+  private async isBraveBrowser(): Promise<boolean> {
+    if (!navigator.brave || typeof navigator.brave.isBrave !== 'function') {
+      return false;
+    }
+
+    try {
+      return await navigator.brave.isBrave();
+    } catch {
+      return false;
+    }
   }
   async importFromURL(url: string): Promise<void> {
     if (!url) {
diff --git a/apps/studio/src/types/window-file-system-access.d.ts b/apps/studio/src/types/window-file-system-access.d.ts
index 5fd2e694b..2f1e68a93 100644
--- a/apps/studio/src/types/window-file-system-access.d.ts
+++ b/apps/studio/src/types/window-file-system-access.d.ts
@@ -2,6 +2,12 @@
 export {};
 
 declare global {
+  interface Navigator {
+    brave?: {
+      isBrave: () => Promise<boolean>;
+    };
+  }
+
   interface Window {
     showDirectoryPicker: (options?: { mode?: 'read' | 'readwrite' }) => Promise<FileSystemDirectoryHandle>;
     showOpenFilePicker: (options?: unknown) => Promise<FileSystemFileHandle[]>;

From 923cc73f0daf01747da760016fe1b87795dcd628 Mon Sep 17 00:00:00 2001
From: Ivan Garcia Sainz-Aja <ivangsa@gmail.com>
Date: Wed, 11 Mar 2026 09:19:33 +0100
Subject: [PATCH 23/23] wrap console.log to disable in prod

---
 .../src/components/Modals/OpenFolderModal.tsx   |  5 +++--
 apps/studio/src/helpers/debug.ts                | 17 +++++++++++++++++
 apps/studio/src/services/app.service.ts         |  3 ++-
 apps/studio/src/services/editor.service.tsx     | 11 ++++++-----
 apps/studio/src/services/local-file-resolver.ts | 17 +++++++++--------
 apps/studio/src/services/parser.service.ts      | 13 ++++++++-----
 apps/studio/src/state/files.state.ts            |  5 +++--
 7 files changed, 48 insertions(+), 23 deletions(-)
 create mode 100644 apps/studio/src/helpers/debug.ts

diff --git a/apps/studio/src/components/Modals/OpenFolderModal.tsx b/apps/studio/src/components/Modals/OpenFolderModal.tsx
index 79a1b8e52..9c3e9c78e 100644
--- a/apps/studio/src/components/Modals/OpenFolderModal.tsx
+++ b/apps/studio/src/components/Modals/OpenFolderModal.tsx
@@ -3,6 +3,7 @@ import { create } from '@ebay/nice-modal-react';
 
 import { ConfirmModal } from './ConfirmModal';
 
+import { debugError, debugLog } from '@/helpers/debug';
 import { useServices } from '../../services';
 
 export const OpenFolderModal = create(() => {
@@ -10,7 +11,7 @@ export const OpenFolderModal = create(() => {
 
   const onSubmit = async () => {
     const toastId = 'open-folder';
-    console.log('[DEBUG:ui] Open Folder — Continue clicked');
+    debugLog('ui', 'Open Folder Continue clicked');
     toast.loading('Granting folder access...', { id: toastId });
     try {
       const granted = await editorSvc.grantFolderAccess();
@@ -20,7 +21,7 @@ export const OpenFolderModal = create(() => {
         toast.dismiss(toastId);
       }
     } catch (err: unknown) {
-      console.error('[DEBUG:ui] Open Folder failed', err);
+      debugError('ui', 'Open Folder failed', err);
       const message = err instanceof Error ? err.message : 'Unknown error';
       toast.error(`Failed to grant folder access: ${message}`, { id: toastId });
     }
diff --git a/apps/studio/src/helpers/debug.ts b/apps/studio/src/helpers/debug.ts
new file mode 100644
index 000000000..071dc9877
--- /dev/null
+++ b/apps/studio/src/helpers/debug.ts
@@ -0,0 +1,17 @@
+const DEBUG_ENABLED = false;
+
+export function debugLog(scope: string, ...args: unknown[]) {
+  if (!DEBUG_ENABLED) {
+    return;
+  }
+
+  console.log(`[DEBUG:${scope}]`, ...args);
+}
+
+export function debugError(scope: string, ...args: unknown[]) {
+  if (!DEBUG_ENABLED) {
+    return;
+  }
+
+  console.error(`[DEBUG:${scope}]`, ...args);
+}
diff --git a/apps/studio/src/services/app.service.ts b/apps/studio/src/services/app.service.ts
index 9815d49c9..8d32aaf32 100644
--- a/apps/studio/src/services/app.service.ts
+++ b/apps/studio/src/services/app.service.ts
@@ -4,6 +4,7 @@ import { show } from '@ebay/nice-modal-react';
 
 import { RedirectedModal } from '../components/Modals';
 
+import { debugLog } from '@/helpers/debug';
 import { appState, filesState } from '@/state';
 
 export class ApplicationService extends AbstractService {
@@ -52,7 +53,7 @@ export class ApplicationService extends AbstractService {
       return;
     }
 
-    console.log('[DEBUG:app] fetchResource', { url, base64: !!base64, share });
+    debugLog('app', 'fetchResource', { url, base64: !!base64, share });
 
     let content = '';
     if (url) {
diff --git a/apps/studio/src/services/editor.service.tsx b/apps/studio/src/services/editor.service.tsx
index 523da20a7..c955c1a12 100644
--- a/apps/studio/src/services/editor.service.tsx
+++ b/apps/studio/src/services/editor.service.tsx
@@ -7,6 +7,7 @@ import { Range, MarkerSeverity } from 'monaco-editor/esm/vs/editor/editor.api';
 import toast from 'react-hot-toast';
 
 import { BrowserNotSupportedModal } from '@/components/Modals';
+import { debugError, debugLog } from '@/helpers/debug';
 import { appState, documentsState, filesState } from '@/state';
 import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
 
@@ -214,7 +215,7 @@ export class EditorService extends AbstractService {
             stat: { mtime: Date.now() },
           };
         } catch (err) {
-          console.error('[DEBUG:editor] Failed to read local file for tree', localPath, err);
+          debugError('editor', 'Failed to read local file for tree', localPath, err);
         }
       }
     }
@@ -286,7 +287,7 @@ export class EditorService extends AbstractService {
       directoryHandle = await window.showDirectoryPicker({ mode: 'read' });
     } catch (err: any) {
       if (err?.name === 'AbortError') return false;
-      console.error('[DEBUG:editor] showDirectoryPicker failed', err);
+      debugError('editor', 'showDirectoryPicker failed', err);
       throw err;
     }
 
@@ -301,7 +302,7 @@ export class EditorService extends AbstractService {
     } catch (err: any) {
       toast.dismiss(folderAccessToastId);
       if (err?.name === 'AbortError') return false;
-      console.error('[DEBUG:editor] showOpenFilePicker failed', err);
+      debugError('editor', 'showOpenFilePicker failed', err);
       throw err;
     }
 
@@ -366,7 +367,7 @@ export class EditorService extends AbstractService {
       throw new Error('URL is required');
     }
 
-    console.log('[DEBUG:editor] importFromURL', url);
+    debugLog('editor', 'importFromURL', url);
 
     const currentUrl = window.location.href.split('?')[0];
     window.history.pushState({}, '', `${currentUrl}?url=${url}`);
@@ -427,7 +428,7 @@ export class EditorService extends AbstractService {
       throw new Error('Invalid file type. Only .json, .yaml, .yml, .avsc, .md, and .markdown files are supported.');
     }
 
-    console.log('[DEBUG:editor] importFile', file.name);
+    debugLog('editor', 'importFile', file.name);
 
     const fileReader = new FileReader();
     fileReader.onload = fileLoadedEvent => {
diff --git a/apps/studio/src/services/local-file-resolver.ts b/apps/studio/src/services/local-file-resolver.ts
index 1d644b5fe..bcb813219 100644
--- a/apps/studio/src/services/local-file-resolver.ts
+++ b/apps/studio/src/services/local-file-resolver.ts
@@ -1,4 +1,5 @@
 import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
+import { debugLog } from '@/helpers/debug';
 
 /**
  * Local File Resolver for AsyncAPI Parser (Stage 2/3)
@@ -31,7 +32,7 @@ export function normaliseRelativePath(basePath: string, relativePath: string): s
   }
 
   const resolved = baseParts.join('/');
-  console.log('[DEBUG:resolver] normaliseRelativePath', { basePath, relativePath, resolved });
+  debugLog('resolver', 'normaliseRelativePath', { basePath, relativePath, resolved });
   return resolved;
 }
 
@@ -56,7 +57,7 @@ export async function getFileHandleFromPath(
 
   for (const dirName of parts) {
     try {
-      console.log('[DEBUG:resolver] getFileHandleFromPath navigating to dir:', dirName);
+      debugLog('resolver', 'getFileHandleFromPath navigating to dir:', dirName);
       currentDir = await currentDir.getDirectoryHandle(dirName);
     } catch {
       throw new Error(
@@ -67,7 +68,7 @@ export async function getFileHandleFromPath(
   }
 
   try {
-    console.log('[DEBUG:resolver] getFileHandleFromPath getting file:', fileName);
+    debugLog('resolver', 'getFileHandleFromPath getting file:', fileName);
     return await currentDir.getFileHandle(fileName);
   } catch {
     throw new Error(
@@ -116,7 +117,7 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
   // the path relative to the directoryHandle (e.g. "schemas/User.avsc").
   const folderPrefix = `${directoryHandle.name  }/`;
 
-  console.log('[DEBUG:resolver] createLocalFileResolver created', { basePath, folderName: directoryHandle.name, folderPrefix });
+  debugLog('resolver', 'createLocalFileResolver created', { basePath, folderName: directoryHandle.name, folderPrefix });
 
   return {
     schema: 'file' as const,
@@ -124,13 +125,13 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
 
     canRead(uri: any) {
       const p = extractPath(uri);
-      console.log('[DEBUG:resolver] canRead called for', p, '(raw uri:', String(uri), ')');
+      debugLog('resolver', 'canRead called for', p, '(raw uri:', String(uri), ')');
       return true; // Accept all file:// URIs — we handle everything in this folder
     },
 
     async read(uri: any): Promise<string> {
       const rawPath = extractPath(uri);
-      console.log('[DEBUG:resolver] read() called for', rawPath, '(raw uri:', String(uri), ')');
+      debugLog('resolver', 'read() called for', rawPath, '(raw uri:', String(uri), ')');
 
       // Strip leading slashes and the folder name prefix to get a path
       // relative to the directoryHandle.
@@ -139,7 +140,7 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
         relativePath = relativePath.slice(folderPrefix.length);
       }
 
-      console.log('[DEBUG:resolver] read() relativePath:', relativePath);
+      debugLog('resolver', 'read() relativePath:', relativePath);
       const fileHandle = await getFileHandleFromPath(directoryHandle, relativePath);
       const file = await fileHandle.getFile();
       const content = await file.text();
@@ -151,7 +152,7 @@ export function createLocalFileResolver(options: LocalFileResolverOptions) {
           fileHandle,
         });
       }
-      console.log('[DEBUG:resolver] read() success for', relativePath, `(${content.length} chars)`);
+      debugLog('resolver', 'read() success for', relativePath, `(${content.length} chars)`);
       return content;
     },
   };
diff --git a/apps/studio/src/services/parser.service.ts b/apps/studio/src/services/parser.service.ts
index a7781c8fe..f989e9b5d 100644
--- a/apps/studio/src/services/parser.service.ts
+++ b/apps/studio/src/services/parser.service.ts
@@ -6,6 +6,7 @@ import { AvroSchemaParser } from '@asyncapi/avro-schema-parser';
 import { ProtoBuffSchemaParser } from '@asyncapi/protobuf-schema-parser';
 import { untilde } from '@asyncapi/parser/cjs/utils';
 
+import { debugLog } from '@/helpers/debug';
 import { isDeepEqual } from '@/helpers';
 import { filesState, documentsState, settingsState } from '@/state';
 import { createLocalFileResolver } from './local-file-resolver';
@@ -74,8 +75,10 @@ export class ParserService extends AbstractService {
     const file = active;
     const useLocalResolver = !!(file?.from === 'file' && file.directoryHandle && file.localPath);
     const useRemoteResolver = !!(file?.from === 'url' && (/^https?:\/\//).test(file.source || ''));
-    console.log(
-      '[DEBUG:parser] parse()', uri,
+    debugLog(
+      'parser',
+      'parse()',
+      uri,
       '\n  file.from:', file?.from,
       '\n  file.source:', file?.source,
       '\n  file.localPath:', file?.localPath,
@@ -306,7 +309,7 @@ export class ParserService extends AbstractService {
   private subscribeToFiles() {
     // Unsubscribe from previous subscription if it exists
     if (this.unsubscribeFiles) {
-      console.log('[DEBUG:parser] subscribeToFiles - cleaning up previous subscription');
+      debugLog('parser', 'subscribeToFiles - cleaning up previous subscription');
       this.unsubscribeFiles();
     }
 
@@ -322,7 +325,7 @@ export class ParserService extends AbstractService {
       const localPathChanged = file.localPath !== oldFile?.localPath;
       const mtimeChanged = file.stat?.mtime !== oldFile?.stat?.mtime;
 
-      console.log('[DEBUG:parser] subscribeToFiles', 'asyncapi', { activeChanged, contentChanged, sourceChanged, directoryHandleChanged, localPathChanged, mtimeChanged });
+      debugLog('parser', 'subscribeToFiles', 'asyncapi', { activeChanged, contentChanged, sourceChanged, directoryHandleChanged, localPathChanged, mtimeChanged });
 
       if (!activeChanged && !contentChanged && !sourceChanged && !directoryHandleChanged && !localPathChanged && !mtimeChanged) {
         return;
@@ -335,7 +338,7 @@ export class ParserService extends AbstractService {
   private subscribeToSettings() {
     // Unsubscribe from previous subscription if it exists
     if (this.unsubscribeSettings) {
-      console.log('[DEBUG:parser] subscribeToSettings - cleaning up previous subscription');
+      debugLog('parser', 'subscribeToSettings - cleaning up previous subscription');
       this.unsubscribeSettings();
     }
 
diff --git a/apps/studio/src/state/files.state.ts b/apps/studio/src/state/files.state.ts
index 0874d2b93..7899e18b0 100644
--- a/apps/studio/src/state/files.state.ts
+++ b/apps/studio/src/state/files.state.ts
@@ -1,5 +1,6 @@
 import { create } from 'zustand';
 import { DirectoryHandle, FileHandle } from '@/helpers/file-system-access.types';
+import { debugLog } from '@/helpers/debug';
 
 // Helper function to extract content and source from localStorage
 const getDocumentFromLocalStorage = () => {
@@ -304,7 +305,7 @@ export const filesState = create<FilesState & FilesActions>((set, get) => ({
       ? { from: before.from, source: before.source, localPath: before.localPath, hasDirectoryHandle: !!before.directoryHandle, hasFileHandle: !!before.fileHandle }
       : '(new file)';
     const logPatch = { from: file.from, source: file.source, localPath: file.localPath, hasDirectoryHandle: !!file.directoryHandle, hasFileHandle: !!file.fileHandle };
-    console.log('[DEBUG:filesState] updateFile', uri, '\n  before:', logBefore, '\n  patch: ', logPatch);
+    debugLog('filesState', 'updateFile', uri, '\n  before:', logBefore, '\n  patch: ', logPatch);
     set((state) => {
       const nextFiles: Record<string, File> = {
         ...state.files,
@@ -320,7 +321,7 @@ export const filesState = create<FilesState & FilesActions>((set, get) => ({
     });
     const after = get().files[String(uri)];
     const logAfter = { from: after.from, source: after.source, localPath: after.localPath, hasDirectoryHandle: !!after.directoryHandle, hasFileHandle: !!after.fileHandle };
-    console.log('[DEBUG:filesState] updateFile', uri, '\n  after: ', logAfter);
+    debugLog('filesState', 'updateFile', uri, '\n  after: ', logAfter);
   },
   setActiveFile(uri: string) {
     const selected = get().files[String(uri)];