collabmd 0.1.45 → 0.1.47

package/src/client/application/structurizr-preview-controller.js

@@ -0,0 +1,395 @@
+import { resolveAppPath } from '../domain/runtime-paths.js';
+import { setDiagramActionButtonIcon } from '../domain/diagram-action-icons.js';
+
+const SYNC_DEBOUNCE_MS = 300;
+const FRAME_FIT_ATTEMPTS = 20;
+const FRAME_FIT_INTERVAL_MS = 50;
+
+function decodeViewKey(hash = '') {
+  const normalized = String(hash ?? '').replace(/^#/, '');
+  if (!normalized) {
+    return '';
+  }
+
+  try {
+    return decodeURIComponent(normalized);
+  } catch {
+    return normalized;
+  }
+}
+
+function readFrameState(iframe) {
+  try {
+    const frameDocument = iframe?.contentDocument;
+    const layer = frameDocument?.querySelector('.joint-layers');
+    const viewport = frameDocument?.querySelector('#diagram-viewport');
+    const zoom = layer ? new DOMMatrixReadOnly(getComputedStyle(layer).transform).a : 0;
+    return {
+      scrollLeft: viewport?.scrollLeft ?? 0,
+      scrollTop: viewport?.scrollTop ?? 0,
+      zoom: Number.isFinite(zoom) && zoom > 0 ? zoom : null,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export class StructurizrPreviewController {
+  constructor({
+    enabled = false,
+    syncWorkspace,
+  }) {
+    this.enabled = Boolean(enabled);
+    this.syncWorkspace = syncWorkspace;
+    this.iframe = null;
+    this.shell = null;
+    this.status = null;
+    this.maximizeButton = null;
+    this.filePath = null;
+    this.viewKey = '';
+    this.lastVersion = null;
+    this.syncTimer = null;
+    this.syncToken = 0;
+    this.frameFitTimer = null;
+    this.frameHost = null;
+    this.pendingIframe = null;
+    this.pendingVersion = null;
+    this.handleFrameLoad = (event) => {
+      const iframe = event?.currentTarget || this.iframe;
+      if (!iframe) {
+        return;
+      }
+
+      try {
+        if (iframe === this.iframe) {
+          this.viewKey = decodeViewKey(iframe.contentWindow?.location?.hash || '') || this.viewKey;
+          iframe.contentWindow?.addEventListener('hashchange', this.handleFrameHashChange);
+        }
+        this.prepareFrame(iframe);
+      } catch {
+        if (iframe === this.pendingIframe) {
+          this.commitPendingIframe(iframe);
+        }
+      }
+    };
+    this.handleFrameHashChange = () => {
+      try {
+        this.viewKey = decodeViewKey(this.iframe?.contentWindow?.location?.hash || '') || this.viewKey;
+      } catch {
+        // Ignore inaccessible frame locations.
+      }
+    };
+  }
+
+  setStatus(message = '', { error = false } = {}) {
+    if (!this.status) {
+      return;
+    }
+
+    this.status.textContent = message;
+    this.status.hidden = !message;
+    this.status.classList.toggle('is-error', error);
+  }
+
+  prepareFrame(iframe = this.iframe) {
+    const frameDocument = iframe?.contentDocument;
+    if (!frameDocument?.head) {
+      if (iframe === this.pendingIframe) {
+        this.commitPendingIframe(iframe);
+      }
+      return;
+    }
+
+    iframe.contentWindow?.dispatchEvent(new Event('resize'));
+    this.scheduleFrameFit(iframe, iframe === this.pendingIframe ? () => this.commitPendingIframe(iframe) : null);
+  }
+
+  fitFrameToCanvas(iframe = this.iframe) {
+    const frameDocument = iframe?.contentDocument;
+    const canvas = frameDocument?.querySelector('#diagram-canvas');
+    if (!canvas) {
+      return false;
+    }
+    if (iframe === this.pendingIframe && !frameDocument.querySelector('.joint-layers')) {
+      return false;
+    }
+
+    try {
+      const diagram = iframe?.contentWindow?.structurizr?.diagram;
+      diagram?.setEmbedded?.(true);
+      diagram?.resize?.();
+      diagram?.zoomToWidthOrHeight?.();
+    } catch {
+      // The frame can be cross-origin in custom deployments; the CSS crop still applies.
+    }
+
+    const { width, height } = canvas.getBoundingClientRect();
+    if (!width || !height) {
+      return false;
+    }
+
+    return true;
+  }
+
+  disposeFrame(iframe) {
+    if (!iframe) {
+      return;
+    }
+
+    try {
+      iframe.contentWindow?.removeEventListener?.('hashchange', this.handleFrameHashChange);
+    } catch {
+      // Ignore inaccessible frame windows during cleanup.
+    }
+    iframe.removeEventListener('load', this.handleFrameLoad);
+    iframe.remove();
+  }
+
+  discardPendingIframe() {
+    if (!this.pendingIframe) {
+      return;
+    }
+
+    clearTimeout(this.frameFitTimer);
+    this.frameFitTimer = null;
+    this.disposeFrame(this.pendingIframe);
+    this.pendingIframe = null;
+    this.pendingVersion = null;
+  }
+
+  commitPendingIframe(iframe) {
+    if (iframe !== this.pendingIframe || !this.shell?.isConnected) {
+      return;
+    }
+
+    const previousIframe = this.iframe;
+    const nextVersion = this.pendingVersion;
+    const frameState = readFrameState(previousIframe);
+    this.pendingIframe = null;
+    this.pendingVersion = null;
+    if (frameState?.zoom) {
+      try {
+        iframe.contentWindow?.structurizr?.diagram?.zoomTo?.(frameState.zoom);
+      } catch {
+        // Keep the new diagram usable when a custom viewer does not expose zoom controls.
+      }
+    }
+    try {
+      const viewport = iframe.contentDocument?.querySelector('#diagram-viewport');
+      if (viewport && frameState) {
+        viewport.scrollLeft = frameState.scrollLeft;
+        viewport.scrollTop = frameState.scrollTop;
+      }
+    } catch {
+      // Cross-origin custom viewers cannot restore viewport coordinates.
+    }
+    this.disposeFrame(previousIframe);
+    iframe.style.visibility = '';
+    iframe.style.pointerEvents = '';
+    iframe.removeAttribute('aria-hidden');
+    this.iframe = iframe;
+    this.lastVersion = nextVersion;
+
+    try {
+      this.viewKey = decodeViewKey(iframe.contentWindow?.location?.hash || '') || this.viewKey;
+      iframe.contentWindow?.addEventListener('hashchange', this.handleFrameHashChange);
+    } catch {
+      // Cross-origin deployments cannot expose the frame hash.
+    }
+    this.setStatus('');
+  }
+
+  createIframe() {
+    const iframe = document.createElement('iframe');
+    iframe.className = 'structurizr-preview-iframe';
+    iframe.title = 'Structurizr architecture diagram';
+    iframe.loading = 'eager';
+    iframe.referrerPolicy = 'same-origin';
+    iframe.addEventListener('load', this.handleFrameLoad);
+    return iframe;
+  }
+
+  syncMaximizeButtonState() {
+    if (!this.maximizeButton || !this.shell) {
+      return;
+    }
+
+    const isMaximized = this.shell.classList.contains('is-maximized');
+    setDiagramActionButtonIcon(this.maximizeButton, isMaximized ? 'restore' : 'maximize');
+    const label = isMaximized ? 'Restore diagram size' : 'Maximize diagram';
+    this.maximizeButton.title = label;
+    this.maximizeButton.setAttribute('aria-label', label);
+  }
+
+  setMaximized(shouldMaximize) {
+    const isMaximized = Boolean(shouldMaximize);
+    this.shell?.classList.toggle('is-maximized', isMaximized);
+    document.body?.classList.toggle('structurizr-maximized-open', isMaximized);
+    this.syncMaximizeButtonState();
+    this.iframe?.contentWindow?.dispatchEvent(new Event('resize'));
+  }
+
+  scheduleFrameFit(iframe = this.iframe, onReady = null) {
+    if (!iframe) {
+      return;
+    }
+
+    clearTimeout(this.frameFitTimer);
+    let attempts = 0;
+    const fit = () => {
+      this.frameFitTimer = null;
+      if (this.fitFrameToCanvas(iframe) || attempts >= FRAME_FIT_ATTEMPTS) {
+        onReady?.();
+        return;
+      }
+
+      attempts += 1;
+      this.frameFitTimer = setTimeout(fit, FRAME_FIT_INTERVAL_MS);
+    };
+    fit();
+  }
+
+  mount(renderHost, filePath) {
+    const fileChanged = Boolean(this.filePath && this.filePath !== filePath);
+    if (fileChanged) {
+      this.setMaximized(false);
+      this.discardPendingIframe();
+      this.disposeFrame(this.iframe);
+      this.iframe = null;
+      this.lastVersion = null;
+      this.viewKey = '';
+    }
+
+    this.filePath = filePath;
+
+    if (this.shell?.isConnected && this.shell.parentElement === renderHost) {
+      return;
+    }
+
+    clearTimeout(this.frameFitTimer);
+    this.frameFitTimer = null;
+    this.shell = document.createElement('section');
+    this.shell.className = 'structurizr-preview-shell diagram-preview-shell';
+    this.shell.dataset.structurizrPreview = 'true';
+
+    const header = document.createElement('div');
+    header.className = 'structurizr-preview-header diagram-preview-toolbar';
+
+    const label = document.createElement('span');
+    label.className = 'structurizr-preview-label';
+    label.textContent = String(filePath).split('/').pop()?.replace(/\.dsl$/i, '') || 'Structurizr';
+
+    this.maximizeButton = document.createElement('button');
+    this.maximizeButton.type = 'button';
+    this.maximizeButton.className = 'structurizr-preview-btn ui-preview-action ui-preview-action--icon-only';
+    this.maximizeButton.dataset.action = 'toggle-maximize';
+    this.maximizeButton.addEventListener('click', (event) => {
+      event.preventDefault();
+      this.setMaximized(!this.shell?.classList.contains('is-maximized'));
+    });
+    header.append(label, this.maximizeButton);
+    this.syncMaximizeButtonState();
+
+    this.status = document.createElement('div');
+    this.status.className = 'structurizr-preview-status';
+    this.status.setAttribute('aria-live', 'polite');
+    this.status.setAttribute('role', 'status');
+    this.status.hidden = true;
+
+    this.frameHost = document.createElement('div');
+    this.frameHost.className = 'structurizr-preview-stage';
+    this.shell.append(header, this.status, this.frameHost);
+
+    renderHost?.replaceChildren(this.shell);
+    this.iframe = null;
+    this.pendingIframe = null;
+    this.pendingVersion = null;
+    this.lastVersion = null;
+  }
+
+  async render({ filePath, renderHost, source = '' }) {
+    this.mount(renderHost, filePath);
+    return this.syncNow({ filePath, source: String(source ?? '') });
+  }
+
+  queueSync({ filePath, source = '' } = {}) {
+    clearTimeout(this.syncTimer);
+    this.syncTimer = setTimeout(() => {
+      this.syncTimer = null;
+      void this.syncNow({ filePath, source: String(source ?? '') });
+    }, SYNC_DEBOUNCE_MS);
+  }
+
+  async syncNow({ filePath, source = '' } = {}) {
+    if (filePath !== this.filePath) {
+      return false;
+    }
+
+    const token = ++this.syncToken;
+    if (!this.enabled) {
+      this.setStatus('Structurizr preview is not configured. Start CollabMD with --local-structurizr.', { error: true });
+      return false;
+    }
+
+    if (!this.iframe) {
+      this.setStatus('Validating Structurizr workspace…');
+    }
+
+    try {
+      const payload = await this.syncWorkspace({ path: filePath, source });
+      if (token !== this.syncToken || filePath !== this.filePath) {
+        return false;
+      }
+
+      const nextVersion = payload?.version || null;
+      const route = resolveAppPath('/workspace/1/diagrams');
+      const hash = this.viewKey ? `#${encodeURIComponent(this.viewKey)}` : '';
+      if (!this.iframe) {
+        const iframe = this.createIframe();
+        this.iframe = iframe;
+        this.frameHost?.appendChild(iframe);
+        iframe.src = `${route}${hash}`;
+        this.lastVersion = nextVersion;
+      } else if (nextVersion !== this.lastVersion) {
+        this.discardPendingIframe();
+        const iframe = this.createIframe();
+        iframe.style.visibility = 'hidden';
+        iframe.style.pointerEvents = 'none';
+        iframe.setAttribute('aria-hidden', 'true');
+        this.pendingIframe = iframe;
+        this.pendingVersion = nextVersion;
+        this.frameHost?.appendChild(iframe);
+        iframe.src = `${route}${hash}`;
+      }
+
+      this.setStatus('');
+      return true;
+    } catch (error) {
+      if (token !== this.syncToken || filePath !== this.filePath) {
+        return false;
+      }
+
+      this.setStatus(error?.message || 'Failed to load Structurizr workspace.', { error: true });
+      return false;
+    }
+  }
+
+  reset() {
+    this.setMaximized(false);
+    clearTimeout(this.syncTimer);
+    this.syncTimer = null;
+    clearTimeout(this.frameFitTimer);
+    this.frameFitTimer = null;
+    this.syncToken += 1;
+    this.discardPendingIframe();
+    this.disposeFrame(this.iframe);
+    this.iframe = null;
+    this.frameHost = null;
+    this.shell = null;
+    this.status = null;
+    this.maximizeButton = null;
+    this.filePath = null;
+    this.lastVersion = null;
+    this.viewKey = '';
+  }
+}

package/src/client/application/workspace-coordinator.js

@@ -21,6 +21,7 @@ export class WorkspaceCoordinator {
     getDisplayName,
     getFileList,
     getLineWrappingEnabled,
+    getVimModeEnabled,
     getLocalUser,
     getStoredUserName,
     getTheme,
@@ -28,8 +29,10 @@ export class WorkspaceCoordinator {
     isDrawioFile,
     isExcalidrawFile,
     isImageFile,
+    isPdfFile,
     isMermaidFile,
     isPlantUmlFile,
+    isStructurizrWorkspaceFile,
     isTabActive,
     loadBootstrapContent = null,
     loadEditorSessionClass,
@@ -49,6 +52,8 @@ export class WorkspaceCoordinator {
     onRenderExcalidrawPreview,
     onRenderDrawioPreview,
     onRenderImagePreview,
+    onRenderPdfPreview,
+    onRenderStructurizrPreview,
     onSyncWrapToggle,
     onUpdateActiveFile,
     onUpdateCurrentFile,
@@ -68,6 +73,7 @@ export class WorkspaceCoordinator {
     this.getDisplayName = getDisplayName;
     this.getFileList = getFileList;
     this.getLineWrappingEnabled = getLineWrappingEnabled;
+    this.getVimModeEnabled = getVimModeEnabled ?? (() => false);
     this.getLocalUser = getLocalUser;
     this.getStoredUserName = getStoredUserName;
     this.getTheme = getTheme;
@@ -75,8 +81,10 @@ export class WorkspaceCoordinator {
     this.isDrawioFile = isDrawioFile ?? (() => false);
     this.isExcalidrawFile = isExcalidrawFile ?? (() => false);
     this.isImageFile = isImageFile ?? (() => false);
+    this.isPdfFile = isPdfFile ?? (() => false);
     this.isMermaidFile = isMermaidFile ?? (() => false);
     this.isPlantUmlFile = isPlantUmlFile ?? (() => false);
+    this.isStructurizrWorkspaceFile = isStructurizrWorkspaceFile ?? (() => false);
     this.isTabActive = isTabActive;
     this.loadBootstrapContent = loadBootstrapContent;
     this.loadEditorSessionClassPort = loadEditorSessionClass;
@@ -96,6 +104,8 @@ export class WorkspaceCoordinator {
     this.onRenderDrawioPreview = onRenderDrawioPreview;
     this.onRenderExcalidrawPreview = onRenderExcalidrawPreview;
     this.onRenderImagePreview = onRenderImagePreview;
+    this.onRenderPdfPreview = onRenderPdfPreview;
+    this.onRenderStructurizrPreview = onRenderStructurizrPreview;
     this.onSyncWrapToggle = onSyncWrapToggle;
     this.onUpdateActiveFile = onUpdateActiveFile;
     this.onUpdateCurrentFile = onUpdateCurrentFile;
@@ -171,12 +181,19 @@ export class WorkspaceCoordinator {
     filePath,
     isExcalidraw = false,
     isImage = false,
+    isPdf = false,
     supportsBacklinks,
   }) {
     if (isExcalidraw) this.onRenderExcalidrawPreview(filePath);
     if (isBase || isBaseFilePath(filePath)) this.onRenderBasePreview(filePath);
     if (isDrawio) this.onRenderDrawioPreview(filePath);
     if (isImage) this.onRenderImagePreview(filePath);
+    if (isPdf) this.onRenderPdfPreview(filePath);
+    if (this.isStructurizrWorkspaceFile(filePath)) {
+      this.onRenderStructurizrPreview(filePath, {
+        source: this.session?.getText?.() ?? '',
+      });
+    }
     this.onSyncWrapToggle();
     if (supportsBacklinks) this.loadBacklinks(filePath);
   }
@@ -192,13 +209,15 @@ export class WorkspaceCoordinator {
     const isExcalidraw = this.isExcalidrawFile(filePath);
     const isBase = this.isBaseFile(filePath);
     const isImage = this.isImageFile(filePath);
+    const isPdf = this.isPdfFile(filePath);
     const isMermaid = this.isMermaidFile(filePath);
     const isPlantUml = this.isPlantUmlFile(filePath);
+    const isStructurizrWorkspace = this.isStructurizrWorkspaceFile(filePath);
 
     if (
       filePath === this.stateStore.currentFilePath
       && normalizedDrawioMode === currentDrawioMode
-      && (this.session || isDrawio || isExcalidraw || isImage)
+      && (this.session || isDrawio || isExcalidraw || isImage || isPdf)
     ) {
       this.onUpdateActiveFile(filePath);
       this.onUpdateLobbyCurrentFile(filePath);
@@ -211,11 +230,11 @@ export class WorkspaceCoordinator {
     this.cleanupSession();
     const chromeState = this.prepareForFileOpen(filePath, {
       drawioMode: normalizedDrawioMode,
-      resetConnectionState: !isDrawio && !isExcalidraw && !isImage,
+      resetConnectionState: !isDrawio && !isExcalidraw && !isImage && !isPdf,
     });
     this.reportFileOpenMetric('open_started', loadToken, { filePath });
 
-    if (isDrawio || isExcalidraw || isImage) {
+    if (isDrawio || isExcalidraw || isImage || isPdf) {
       this.onSessionAssigned?.(null);
 
       if (loadToken !== this.stateStore.sessionLoadToken) {
@@ -229,6 +248,7 @@ export class WorkspaceCoordinator {
         isDrawio,
         isExcalidraw,
         isImage,
+        isPdf,
         session: null,
         supportsBacklinks: chromeState.supportsBacklinks,
       });
@@ -241,6 +261,7 @@ export class WorkspaceCoordinator {
       getFileList: this.getFileList,
       lineWrappingEnabled: this.getLineWrappingEnabled(),
       localUser: this.getLocalUser(),
+      vimModeEnabled: this.getVimModeEnabled(),
       onAwarenessChange: (users) => this.onFileAwarenessChange(users),
       onConnectionChange: (state) => this.onConnectionChange(state),
       onCommentsChange: (threads) => this.onCommentsChange?.(threads),
@@ -253,6 +274,7 @@ export class WorkspaceCoordinator {
           isBase,
           isMermaid,
           isPlantUml,
+          isStructurizrWorkspace,
         });
       },
       onImagePaste: (file) => this.onImagePaste?.(file),

package/src/client/application/workspace-preview-controller.js

@@ -2,6 +2,7 @@ import {
   isBaseFilePath,
   isDiagramFilePath,
   isMarkdownFilePath,
+  isStructurizrFilePath,
 } from '../../domain/file-kind.js';
 import { resolveApiUrl } from '../domain/runtime-paths.js';
 
@@ -18,13 +19,16 @@ export class WorkspacePreviewController {
     isExcalidrawFile,
     isBaseFile,
     isImageFile,
+    isPdfFile,
     isMermaidFile,
     isPlantUmlFile,
     layoutController,
     outlineController,
     previewRenderer,
+    pdfPreview = null,
     schedulePreviewLayoutSync,
     scrollSyncController,
+    structurizrPreview = null,
     videoEmbed,
   }) {
     this.backlinksPanel = backlinksPanel;
@@ -46,13 +50,20 @@ export class WorkspacePreviewController {
     this.isExcalidrawFile = isExcalidrawFile ?? (() => false);
     this.isBaseFile = isBaseFile ?? isBaseFilePath;
     this.isImageFile = isImageFile ?? (() => false);
+    this.isPdfFile = isPdfFile ?? (() => false);
     this.isMermaidFile = isMermaidFile ?? (() => false);
     this.isPlantUmlFile = isPlantUmlFile ?? (() => false);
     this.layoutController = layoutController;
     this.outlineController = outlineController;
     this.previewRenderer = previewRenderer;
+    this.pdfPreview = pdfPreview ?? { cancel() {}, render() {} };
     this.schedulePreviewLayoutSyncCallback = schedulePreviewLayoutSync;
     this.scrollSyncController = scrollSyncController;
+    this.structurizrPreview = structurizrPreview ?? {
+      queueSync() {},
+      render: async () => false,
+      reset() {},
+    };
     this.videoEmbed = videoEmbed;
   }
 
@@ -81,12 +92,16 @@ export class WorkspacePreviewController {
   }
 
   resetPreviewMode() {
+    this.pdfPreview.cancel();
     this.elements.previewContent?.classList.remove('is-drawio-file-preview');
     this.elements.previewContent?.classList.remove('is-excalidraw-file-preview');
     this.elements.previewContent?.classList.remove('is-base-file-preview');
     this.elements.previewContent?.classList.remove('is-image-file-preview');
+    this.elements.previewContent?.classList.remove('is-pdf-file-preview');
     this.elements.previewContent?.classList.remove('is-mermaid-file-preview');
     this.elements.previewContent?.classList.remove('is-plantuml-file-preview');
+    this.elements.previewContent?.classList.remove('is-structurizr-file-preview');
+    this.structurizrPreview.reset();
   }
 
   syncFileChrome(filePath, { drawioMode = null, preferPreviewForBase = false } = {}) {
@@ -94,9 +109,11 @@ export class WorkspacePreviewController {
     const isExcalidraw = this.isExcalidrawFile(filePath);
     const isBase = this.isBaseFile(filePath);
     const isImage = this.isImageFile(filePath);
+    const isPdf = this.isPdfFile(filePath);
     const isMarkdown = isMarkdownFilePath(filePath);
     const isMermaid = this.isMermaidFile(filePath);
     const isPlantUml = this.isPlantUmlFile(filePath);
+    const isStructurizr = isStructurizrFilePath(filePath);
     const isDiagramFile = isDiagramFilePath(filePath);
     const usesHeaderBacklinks = isExcalidraw || (isDrawio && drawioMode !== 'text');
 
@@ -105,11 +122,17 @@ export class WorkspacePreviewController {
     this.elements.editorFindButton?.classList.toggle('hidden', !isMarkdown);
     this.elements.markdownToolbar?.classList.toggle('hidden', !isMarkdown);
     this.elements.exportMenuGroup?.classList.toggle('hidden', !isMarkdown);
-    this.elements.outlineToggle?.classList.toggle('hidden', isDiagramFile || isImage || isBase);
+    this.elements.outlineToggle?.classList.toggle('hidden', isDiagramFile || isImage || isPdf || isBase);
     this.elements.previewContent?.classList.toggle('is-mermaid-file-preview', isMermaid);
     this.elements.previewContent?.classList.toggle('is-plantuml-file-preview', isPlantUml);
+    this.elements.previewContent?.classList.toggle('is-structurizr-file-preview', isStructurizr);
+
+    if (isStructurizr) {
+      this.outlineController.close();
+      this.backlinksPanel.clear();
+    }
 
-    if ((isDrawio && drawioMode !== 'text') || isExcalidraw || isImage || (isBase && preferPreviewForBase)) {
+    if ((isDrawio && drawioMode !== 'text') || isExcalidraw || isImage || isPdf || (isBase && preferPreviewForBase)) {
       this.layoutController.setView('preview', { persist: false });
       this.outlineController.close();
       this.backlinksPanel.clear();
@@ -238,6 +261,37 @@ export class WorkspacePreviewController {
     this.schedulePreviewLayoutSyncCallback({ delayMs: 0 });
   }
 
+  renderPdfFilePreview(filePath) {
+    const previewElement = this.elements.previewContent;
+    if (!previewElement) {
+      return;
+    }
+
+    this.videoEmbed?.detachForCommit();
+    this.drawioEmbed.detachForCommit();
+    this.excalidrawEmbed.detachForCommit();
+    this.resetPreviewMode();
+    previewElement.classList.add('is-pdf-file-preview');
+    const renderHost = this.previewRenderer.ensureRenderHost();
+    this.previewRenderer.normalizePreviewChildren(renderHost);
+
+    if (renderHost) {
+      this.pdfPreview.render({
+        filePath,
+        renderHost,
+      });
+      renderHost.style.minHeight = '';
+    }
+
+    previewElement.dataset.renderPhase = 'ready';
+    this.outlineController.close();
+    this.backlinksPanel.clear();
+    this.scrollSyncController.setLargeDocumentMode(false);
+    this.scrollSyncController.invalidatePreviewBlocks();
+    this.videoEmbed?.reconcileEmbeds(previewElement);
+    this.schedulePreviewLayoutSyncCallback({ delayMs: 0 });
+  }
+
   async renderBaseFilePreview(filePath, { source = null } = {}) {
     const previewElement = this.elements.previewContent;
     if (!previewElement) {
@@ -272,6 +326,38 @@ export class WorkspacePreviewController {
     this.schedulePreviewLayoutSyncCallback({ delayMs: 0 });
   }
 
+  async renderStructurizrFilePreview(filePath, { source = null } = {}) {
+    const previewElement = this.elements.previewContent;
+    if (!previewElement) {
+      return;
+    }
+
+    this.videoEmbed?.detachForCommit();
+    this.drawioEmbed.detachForCommit();
+    this.excalidrawEmbed.detachForCommit();
+    this.resetPreviewMode();
+    previewElement.classList.add('is-structurizr-file-preview');
+    const renderHost = this.previewRenderer.ensureRenderHost();
+    this.previewRenderer.normalizePreviewChildren(renderHost);
+    if (renderHost) {
+      renderHost.style.minHeight = '';
+    }
+
+    await this.structurizrPreview.render({
+      filePath,
+      renderHost,
+      source: typeof source === 'string' ? source : (this.getSession()?.getText?.() ?? ''),
+    });
+
+    previewElement.dataset.renderPhase = 'ready';
+    this.outlineController.close();
+    this.backlinksPanel.clear();
+    this.scrollSyncController.setLargeDocumentMode(false);
+    this.scrollSyncController.invalidatePreviewBlocks();
+    this.videoEmbed?.reconcileEmbeds(previewElement);
+    this.schedulePreviewLayoutSyncCallback({ delayMs: 0 });
+  }
+
   renderTextFilePreview({ content = '' } = {}) {
     const previewElement = this.elements.previewContent;
     if (!previewElement) {