From 1a380db8612b78a133cb4b60fbaad424dcd684ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Arve=20Nyg=C3=A5rd?= <mail@arve.in>
Date: Wed, 9 Sep 2026 10:14:54 +0200
Subject: [PATCH] Fix graphics scaling and add window-filling previews

---
 QuickMD/QuickMD/BlockHeightMeasurer.swift     |   6 ++
 QuickMD/QuickMD/MarkdownView.swift            |  24 ++++-
 .../QuickMD/Resources/mermaid-template.html   |  32 +++++-
 QuickMD/QuickMD/Views/ImageBlockView.swift    | 102 ++++++++++++++----
 QuickMD/QuickMD/Views/MermaidBlockView.swift  |  63 +++++++----
 .../BlockHeightMeasurerTests.swift            |   9 ++
 QuickMD/test-image-scaling.md                 |  65 +++++++++++
 scripts/check-mermaid-scaling.swift           |  67 ++++++++++++
 8 files changed, 321 insertions(+), 47 deletions(-)
 create mode 100644 QuickMD/test-image-scaling.md
 create mode 100644 scripts/check-mermaid-scaling.swift

diff --git a/QuickMD/QuickMD/BlockHeightMeasurer.swift b/QuickMD/QuickMD/BlockHeightMeasurer.swift
index bc7a513..621884a 100644
--- a/QuickMD/QuickMD/BlockHeightMeasurer.swift
+++ b/QuickMD/QuickMD/BlockHeightMeasurer.swift
@@ -248,6 +248,12 @@ enum BlockLayout {
         /// the bitmap is decoded, so this is what a measured row starts at.
         static let placeholderHeight: CGFloat = 100
         static let maxDisplayWidth: CGFloat = 600
+
+        /// Scale the fitted 100% width, then keep the result inside the column.
+        static func displayWidth(fontScale: CGFloat, contentWidth: CGFloat) -> CGFloat {
+            let available = max(1, contentWidth)
+            return min(available, min(maxDisplayWidth, available) * fontScale)
+        }
     }
 
     // MARK: Display math
diff --git a/QuickMD/QuickMD/MarkdownView.swift b/QuickMD/QuickMD/MarkdownView.swift
index 63c4d35..e612a5e 100644
--- a/QuickMD/QuickMD/MarkdownView.swift
+++ b/QuickMD/QuickMD/MarkdownView.swift
@@ -46,6 +46,7 @@ struct MarkdownView: View {
     @State private var currentMatchIndex: Int = 0
     @State private var matchBlockIds: [String] = []
     @State private var scrollTrigger: Int = 0
+    @State private var graphicPreview: GraphicPreview?
     @State private var keyMonitor: Any?
     /// The NSWindow hosting this view (set by `WindowConfigurator`); the key
     /// monitor uses it to ignore events addressed to other tabs' windows.
@@ -362,6 +363,13 @@ struct MarkdownView: View {
     /// modifier chain no longer type-checks inside the compiler's budget.
     private var configuredDocumentStack: some View {
         documentStack
+        .disabled(graphicPreview != nil)
+        .accessibilityHidden(graphicPreview != nil)
+        .overlay {
+            if let graphicPreview {
+                GraphicPreviewOverlay(preview: graphicPreview) { self.graphicPreview = nil }
+            }
+        }
         .background(theme.backgroundColor)
         .background(WindowConfigurator { window in
             // Make every QuickMD document window prefer to join existing windows
@@ -557,6 +565,13 @@ struct MarkdownView: View {
                 if let hostWindow, let eventWindow = event.window, eventWindow !== hostWindow {
                     return event
                 }
+                if graphicPreview != nil {
+                    if event.keyCode == 53 {
+                        graphicPreview = nil
+                        return nil
+                    }
+                    return event
+                }
                 let flags = event.modifierFlags.intersection(.deviceIndependentFlagsMask)
 
                 if flags.contains(.command) && event.charactersIgnoringModifiers == "g" {
@@ -680,7 +695,9 @@ struct MarkdownView: View {
                     .padding(.vertical, Metrics.codeOuterVerticalPadding)
 
             case .image(let url, let alt):
-                ImageBlockView(url: url, alt: alt, theme: theme, documentURL: documentURL)
+                ImageBlockView(url: url, alt: alt, theme: theme, documentURL: documentURL,
+                               fontScale: scale, contentWidth: contentWidth,
+                               onEnlarge: { graphicPreview = $0 })
                     .padding(.vertical, Metrics.imageOuterVerticalPadding)
 
             case .blockquote(let content, let level):
@@ -721,7 +738,10 @@ struct MarkdownView: View {
 
             case .mermaidDiagram(let source):
                 MermaidBlockView(blockId: block.id, source: source, theme: theme,
-                                 heightCache: heightCache)
+                                 heightCache: heightCache, fontScale: scale,
+                                 contentWidth: contentWidth,
+                                 onEnlarge: { graphicPreview = $0 })
+                    .id("\(block.id)|\(scale)|\(contentWidth)|\(theme.isDark)")
                     .padding(.vertical, Metrics.mermaidOuterVerticalPadding)
             }
         }
diff --git a/QuickMD/QuickMD/Resources/mermaid-template.html b/QuickMD/QuickMD/Resources/mermaid-template.html
index e820146..bc18e24 100644
--- a/QuickMD/QuickMD/Resources/mermaid-template.html
+++ b/QuickMD/QuickMD/Resources/mermaid-template.html
@@ -13,7 +13,12 @@
 <div id="output"></div>
 <script src="mermaid.min.js"></script>
 <script>
-  function renderDiagram(source, isDark) {
+  var resizeDiagram = null;
+  window.addEventListener('resize', function() {
+    if (resizeDiagram) resizeDiagram();
+  });
+
+  function renderDiagram(source, isDark, scale = 1, fitWindow = false) {
     // renderDiagram may run repeatedly on this page (theme switches re-render
     // in place). mermaid.render can leave its temp element behind after a
     // failed render — remove it or the next render throws on a duplicate id.
@@ -28,6 +33,7 @@
     });
 
     const container = document.getElementById('output');
+    resizeDiagram = null;
     container.innerHTML = '';
 
     // Report height back to Swift. The zoom viewer hosts this same template
@@ -44,7 +50,29 @@
 
     mermaid.render('diagram', source).then(function(result) {
       container.innerHTML = result.svg;
-      reportHeight();
+      const svg = container.querySelector('svg');
+      const bounds = svg.viewBox.baseVal;
+      const naturalWidth = bounds.width;
+      const naturalHeight = bounds.height;
+      if (fitWindow) {
+        document.body.style.display = 'flex';
+        document.body.style.alignItems = 'center';
+        document.body.style.minHeight = '100vh';
+        container.style.width = '100%';
+      }
+      resizeDiagram = function() {
+        if (naturalWidth > 0 && naturalHeight > 0) {
+          const factor = fitWindow
+            ? Math.min(window.innerWidth / naturalWidth, window.innerHeight / naturalHeight)
+            : Math.min(scale * Math.min(1, window.innerWidth / naturalWidth),
+                       window.innerWidth / naturalWidth);
+          svg.style.maxWidth = 'none';
+          svg.style.width = (naturalWidth * factor) + 'px';
+          svg.style.height = (naturalHeight * factor) + 'px';
+        }
+        reportHeight();
+      };
+      resizeDiagram();
     }).catch(function(err) {
       container.innerHTML = '<pre style="color:#e55;font-size:12px;padding:8px;">' +
         err.message.replace(/</g, '&lt;') + '</pre>';
diff --git a/QuickMD/QuickMD/Views/ImageBlockView.swift b/QuickMD/QuickMD/Views/ImageBlockView.swift
index 38495a9..412c6a9 100644
--- a/QuickMD/QuickMD/Views/ImageBlockView.swift
+++ b/QuickMD/QuickMD/Views/ImageBlockView.swift
@@ -14,6 +14,9 @@ struct ImageBlockView: View {
     let alt: String
     let theme: MarkdownTheme
     let documentURL: URL?
+    let fontScale: CGFloat
+    let contentWidth: CGFloat
+    var onEnlarge: (GraphicPreview) -> Void = { _ in }
 
     /// Display width cap and the pre-load placeholder height — see
     /// `BlockLayout.ImageBlock` (shared with `BlockHeightMeasurer`, which starts
@@ -43,11 +46,7 @@ struct ImageBlockView: View {
                             ProgressView()
                                 .frame(height: Metrics.placeholderHeight)
                         case .success(let image):
-                            image
-                                .resizable()
-                                .aspectRatio(contentMode: .fit)
-                                .frame(maxWidth: Metrics.maxDisplayWidth)
-                                .clipShape(RoundedRectangle(cornerRadius: 8))
+                            graphicButton(image, fileURL: nil)
                         case .failure:
                             imageErrorView
                         @unknown default:
@@ -62,22 +61,32 @@ struct ImageBlockView: View {
 
         if !alt.isEmpty {
             Text(alt)
-                .font(.system(size: 12))
+                .font(.system(size: 12 * fontScale))
                 .foregroundColor(theme.secondaryTextColor)
                 .italic()
         }
     }
 
+    private func graphicButton(_ image: Image, fileURL: URL?) -> some View {
+        Button {
+            onEnlarge(.image(image, title: alt, fileURL: fileURL))
+        } label: {
+            image.resizable()
+                .aspectRatio(contentMode: .fit)
+                .frame(maxWidth: Metrics.displayWidth(fontScale: fontScale, contentWidth: contentWidth))
+                .clipShape(RoundedRectangle(cornerRadius: 8))
+        }
+        .buttonStyle(.plain)
+        .help("Click to enlarge image")
+        .accessibilityLabel(alt.isEmpty ? "Enlarge image" : "Enlarge image: \(alt)")
+    }
+
     // MARK: - Local Image View
 
     @ViewBuilder
     private func localImageView(for fileURL: URL) -> some View {
         if let image = localImage {
-            Image(nsImage: image)
-                .resizable()
-                .aspectRatio(contentMode: .fit)
-                .frame(maxWidth: Metrics.maxDisplayWidth)
-                .clipShape(RoundedRectangle(cornerRadius: 8))
+            graphicButton(Image(nsImage: image), fileURL: fileURL)
         } else if isLoadingLocal {
             ProgressView()
                 .frame(height: Metrics.placeholderHeight)
@@ -109,7 +118,7 @@ struct ImageBlockView: View {
             .buttonStyle(.bordered)
             .controlSize(.small)
         }
-        .frame(maxWidth: Metrics.maxDisplayWidth)
+        .frame(maxWidth: Metrics.displayWidth(fontScale: fontScale, contentWidth: contentWidth))
         .padding(.vertical, 12)
     }
 
@@ -162,25 +171,22 @@ struct ImageBlockView: View {
 
     /// Efficiently load and downsample image using ImageIO
     /// This prevents loading huge images (e.g., 4K) at full resolution
-    private static func loadDownsampledImage(from url: URL, maxPixelSize: Int) -> NSImage? {
-        guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else {
-            // Fallback to NSImage if CGImageSource fails
+    private nonisolated static func loadDownsampledImage(from url: URL, maxPixelSize: Int) -> NSImage? {
+        guard let cgImage = loadThumbnail(from: url, maxPixelSize: maxPixelSize) else {
             return NSImage(contentsOf: url)
         }
+        return NSImage(cgImage: cgImage, size: NSSize(width: cgImage.width, height: cgImage.height))
+    }
 
+    fileprivate nonisolated static func loadThumbnail(from url: URL, maxPixelSize: Int) -> CGImage? {
+        guard let source = CGImageSourceCreateWithURL(url as CFURL, nil) else { return nil }
         let options: [CFString: Any] = [
             kCGImageSourceThumbnailMaxPixelSize: maxPixelSize,
             kCGImageSourceCreateThumbnailFromImageAlways: true,
             kCGImageSourceCreateThumbnailWithTransform: true,
             kCGImageSourceShouldCacheImmediately: true
         ]
-
-        guard let cgImage = CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary) else {
-            // Fallback to NSImage if thumbnail creation fails
-            return NSImage(contentsOf: url)
-        }
-
-        return NSImage(cgImage: cgImage, size: NSSize(width: cgImage.width, height: cgImage.height))
+        return CGImageSourceCreateThumbnailAtIndex(source, 0, options as CFDictionary)
     }
 
     // MARK: - URL Resolution
@@ -219,3 +225,55 @@ struct ImageBlockView: View {
         .clipShape(RoundedRectangle(cornerRadius: 6))
     }
 }
+
+// The document owns presentation so the preview covers the whole window,
+// including sidebars, and survives virtualization of the originating row.
+enum GraphicPreview {
+    case image(Image, title: String, fileURL: URL?)
+    case diagram(String, isDark: Bool)
+}
+
+struct GraphicPreviewOverlay: View {
+    let preview: GraphicPreview
+    let onClose: () -> Void
+    @State private var detailedImage: NSImage?
+
+    var body: some View {
+        Group {
+            switch preview {
+            case .image(let image, let title, let fileURL):
+                VStack(spacing: 0) {
+                    HStack {
+                        Text(title.isEmpty ? "Image" : title).lineLimit(1)
+                        Spacer()
+                        Button("Done", action: onClose)
+                            .keyboardShortcut(.cancelAction)
+                    }
+                    .padding()
+                    GeometryReader { geometry in
+                        (detailedImage.map { Image(nsImage: $0) } ?? image)
+                            .resizable()
+                            .aspectRatio(contentMode: .fit)
+                            .frame(width: geometry.size.width, height: geometry.size.height)
+                    }
+                    .padding(16)
+                }
+                .task(id: fileURL) {
+                    detailedImage = nil
+                    guard let fileURL else { return }
+                    let loaded = await Task.detached(priority: .userInitiated) {
+                        ImageBlockView.loadThumbnail(from: fileURL, maxPixelSize: 4096)
+                    }.value
+                    guard !Task.isCancelled else { return }
+                    if let loaded {
+                        detailedImage = NSImage(cgImage: loaded, size: NSSize(width: loaded.width, height: loaded.height))
+                    }
+                }
+            case .diagram(let source, let isDark):
+                MermaidZoomView(source: source, isDark: isDark, onClose: onClose)
+            }
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
+        .background(.background)
+    }
+}
diff --git a/QuickMD/QuickMD/Views/MermaidBlockView.swift b/QuickMD/QuickMD/Views/MermaidBlockView.swift
index 7fe0c83..f260441 100644
--- a/QuickMD/QuickMD/Views/MermaidBlockView.swift
+++ b/QuickMD/QuickMD/Views/MermaidBlockView.swift
@@ -13,8 +13,7 @@ import WebKit
 /// shown instantly instead of re-running the WebView render (no flicker), and
 /// the height is seeded from BlockHeightCache (no scroll jump).
 ///
-/// Zoom (#12): hover reveals a zoom button that opens the diagram in a sheet
-/// with pinch/button magnification.
+/// Clicking the diagram opens a window-filling preview with pinch/button zoom.
 /// Shared store of rendered-diagram snapshots, keyed by (isDark, source).
 /// Written by the inline MermaidBlockView after each successful render; read
 /// back by MermaidBlockView on LazyVStack re-creation AND by the PDF exporter
@@ -44,20 +43,30 @@ struct MermaidBlockView: View {
 
     @State private var diagramHeight: CGFloat
     @State private var snapshot: NSImage?
-    @State private var showZoom = false
+    let fontScale: CGFloat
+    let contentWidth: CGFloat
+    let onEnlarge: (GraphicPreview) -> Void
+
+    private var snapshotKey: String { "\(fontScale)|\(contentWidth)|\(source)" }
     @State private var isHovered = false
 
     /// Padding, corner radius and the un-measured default height — see
     /// `BlockLayout.Mermaid` (shared with `BlockHeightMeasurer`).
     typealias Metrics = BlockLayout.Mermaid
 
-    init(blockId: String, source: String, theme: MarkdownTheme, heightCache: BlockHeightCache) {
+    init(blockId: String, source: String, theme: MarkdownTheme, heightCache: BlockHeightCache,
+         fontScale: CGFloat, contentWidth: CGFloat, onEnlarge: @escaping (GraphicPreview) -> Void) {
         self.blockId = blockId
         self.source = source
         self.theme = theme
         self.heightCache = heightCache
+        self.fontScale = fontScale
+        self.contentWidth = contentWidth
+        self.onEnlarge = onEnlarge
         _diagramHeight = State(initialValue: heightCache.height(for: blockId) ?? Metrics.defaultHeight)
-        _snapshot = State(initialValue: MermaidSnapshotStore.image(source: source, isDark: theme.isDark))
+        let cached = MermaidSnapshotStore.image(source: "\(fontScale)|\(contentWidth)|\(source)", isDark: theme.isDark)
+        _snapshot = State(initialValue: cached)
+        if let cached { _diagramHeight = State(initialValue: cached.size.height) }
     }
 
     var body: some View {
@@ -75,12 +84,16 @@ struct MermaidBlockView: View {
                     MermaidWebView(
                         source: source,
                         isDark: theme.isDark,
+                        fontScale: fontScale,
                         diagramHeight: $diagramHeight,
                         onHeight: { height in
                             heightCache.set(height, for: blockId)
                         },
                         onSnapshot: { image in
-                            MermaidSnapshotStore.set(image, source: source, isDark: theme.isDark)
+                            MermaidSnapshotStore.set(image, source: snapshotKey, isDark: theme.isDark)
+                            if fontScale == 1 {
+                                MermaidSnapshotStore.set(image, source: source, isDark: theme.isDark)
+                            }
                         }
                     )
                     .frame(height: diagramHeight)
@@ -88,8 +101,16 @@ struct MermaidBlockView: View {
             }
             .clipShape(RoundedRectangle(cornerRadius: Metrics.cornerRadius))
 
+            // A transparent button also catches clicks over the embedded WKWebView.
+            Button { onEnlarge(.diagram(source, isDark: theme.isDark)) } label: {
+                Color.clear.contentShape(Rectangle())
+            }
+            .buttonStyle(.plain)
+            .accessibilityLabel("Enlarge diagram")
+            .help("Click to enlarge diagram")
+
             Button {
-                showZoom = true
+                onEnlarge(.diagram(source, isDark: theme.isDark))
             } label: {
                 Image(systemName: "arrow.up.left.and.arrow.down.right")
                     .font(.system(size: 11))
@@ -108,21 +129,18 @@ struct MermaidBlockView: View {
         .onHover { hovering in
             isHovered = hovering
         }
-        .sheet(isPresented: $showZoom) {
-            MermaidZoomView(source: source, isDark: theme.isDark)
-        }
     }
 }
 
-// MARK: - Zoom Sheet (#12)
+// MARK: - Window-filling preview
 
 /// Full-size diagram viewer: pinch-to-zoom (native WKWebView magnification)
 /// plus explicit zoom buttons. Scrolling stays INSIDE this web view (it is a
 /// plain WKWebView, not the scroll-passthrough subclass used inline).
-private struct MermaidZoomView: View {
+struct MermaidZoomView: View {
     let source: String
     let isDark: Bool
-    @Environment(\.dismiss) private var dismiss
+    let onClose: () -> Void
     @State private var controller = ZoomWebViewController()
 
     var body: some View {
@@ -138,14 +156,14 @@ private struct MermaidZoomView: View {
                 Button { controller.resetZoom() } label: {
                     Image(systemName: "1.magnifyingglass")
                 }
-                .help("Actual size")
+                .help("Fit diagram to window")
                 Button { controller.zoom(by: 1.25) } label: {
                     Image(systemName: "plus.magnifyingglass")
                 }
                 .help("Zoom in")
                 Divider().frame(height: 16)
-                Button("Done") { dismiss() }
-                    .keyboardShortcut(.defaultAction)
+                Button("Done", action: onClose)
+                    .keyboardShortcut(.cancelAction)
             }
             .padding(.horizontal, 16)
             .padding(.vertical, 10)
@@ -154,11 +172,11 @@ private struct MermaidZoomView: View {
 
             ZoomableMermaidWebView(source: source, isDark: isDark, controller: controller)
         }
-        .frame(minWidth: 700, idealWidth: 900, minHeight: 500, idealHeight: 650)
+        .frame(maxWidth: .infinity, maxHeight: .infinity)
     }
 }
 
-/// Holds a weak reference to the zoom sheet's web view so toolbar buttons can
+/// Holds a weak reference to the preview's web view so toolbar buttons can
 /// drive `magnification` directly (pinch gestures work natively alongside).
 /// Main-thread by convention (button actions); not @MainActor for older-SDK
 /// compatibility — see BlockHeightCache note in TextBlockView.swift.
@@ -215,7 +233,7 @@ private struct ZoomableMermaidWebView: NSViewRepresentable {
                 """, completionHandler: nil)
             guard let data = try? JSONSerialization.data(withJSONObject: source, options: [.fragmentsAllowed]),
                   let jsLiteral = String(data: data, encoding: .utf8) else { return }
-            webView.evaluateJavaScript("renderDiagram(\(jsLiteral), \(isDark ? "true" : "false"));",
+            webView.evaluateJavaScript("renderDiagram(\(jsLiteral), \(isDark ? "true" : "false"), 1, true);",
                                        completionHandler: nil)
         }
     }
@@ -237,6 +255,7 @@ private class ScrollPassthroughWebView: WKWebView {
 private struct MermaidWebView: NSViewRepresentable {
     let source: String
     let isDark: Bool
+    let fontScale: CGFloat
     @Binding var diagramHeight: CGFloat
     let onHeight: (CGFloat) -> Void
     let onSnapshot: (NSImage) -> Void
@@ -263,7 +282,9 @@ private struct MermaidWebView: NSViewRepresentable {
 
     func updateNSView(_ webView: WKWebView, context: Context) {
         // Avoid re-rendering if content hasn't changed
-        if context.coordinator.lastSource == source && context.coordinator.lastIsDark == isDark {
+        if context.coordinator.lastSource == source,
+           context.coordinator.lastIsDark == isDark,
+           context.coordinator.parent.fontScale == fontScale {
             return
         }
         context.coordinator.parent = self
@@ -295,7 +316,7 @@ private struct MermaidWebView: NSViewRepresentable {
             guard templateLoaded, let source = lastSource, let isDark = lastIsDark else { return }
             guard let data = try? JSONSerialization.data(withJSONObject: source, options: [.fragmentsAllowed]),
                   let jsLiteral = String(data: data, encoding: .utf8) else { return }
-            webView.evaluateJavaScript("renderDiagram(\(jsLiteral), \(isDark ? "true" : "false"));",
+            webView.evaluateJavaScript("renderDiagram(\(jsLiteral), \(isDark ? "true" : "false"), \(parent.fontScale));",
                                        completionHandler: nil)
         }
 
diff --git a/QuickMD/QuickMDTests/BlockHeightMeasurerTests.swift b/QuickMD/QuickMDTests/BlockHeightMeasurerTests.swift
index 2d03eb5..d178a81 100644
--- a/QuickMD/QuickMDTests/BlockHeightMeasurerTests.swift
+++ b/QuickMD/QuickMDTests/BlockHeightMeasurerTests.swift
@@ -18,6 +18,15 @@ import AppKit
 /// comes from `BlockLayout`, the one place the views read it from too.
 final class BlockHeightMeasurerTests: XCTestCase {
 
+    func testImageScalingUsesFittedBaselineAndStaysInsideColumn() {
+        let width = BlockLayout.ImageBlock.displayWidth
+        XCTAssertEqual(width(1, 1200), 600)
+        XCTAssertEqual(width(1.5, 1200), 900)
+        XCTAssertEqual(width(0.75, 1200), 450)
+        XCTAssertEqual(width(0.75, 400), 300)
+        XCTAssertEqual(width(1.5, 400), 400)
+    }
+
     // MARK: - Fixtures
 
     private let widths: [CGFloat] = [400, 600, 800, 1000]
diff --git a/QuickMD/test-image-scaling.md b/QuickMD/test-image-scaling.md
new file mode 100644
index 0000000..7dbfc96
--- /dev/null
+++ b/QuickMD/test-image-scaling.md
@@ -0,0 +1,65 @@
+# Image and diagram scaling
+
+This document compares ordinary text, a table, a PNG image, and a Mermaid
+diagram at different viewing scales. Keep the window size fixed while changing
+the text size or zoom, and compare the readability of each element.
+
+## Text
+
+The document viewer should keep illustrated content readable alongside the
+surrounding text. This paragraph provides a reference for **bold text**,
+*italic text*, and `inline code` as the viewing scale changes.
+
+Reference sentence: Open the document, review the diagram, and check the result.
+
+## Table
+
+| Element | What to compare | At a larger viewing scale |
+|:--------|:----------------|:--------------------------|
+| Paragraph | Character size and line wrapping | Is the text larger? |
+| Table | Cell text and row height | Does the table scale with the paragraph? |
+| PNG image | Image width and text inside the image | Does the image grow too? |
+| Mermaid diagram | Node size, labels, and arrows | Are labels still readable beside the paragraph? |
+
+## PNG image
+
+The following local PNG is an existing QuickMD screenshot. Compare the text
+inside the image with this sentence before and after increasing the viewing
+scale. The image uses standard Markdown without an explicit width or height.
+
+![QuickMD screenshot with document text for comparing image and paragraph scaling](Screenshots/screenshot-1.png)
+
+Reference sentence: Open the document, review the diagram, and check the result.
+
+## Mermaid diagram
+
+This diagram contains short labels so their size can be compared with the
+surrounding body text. It has no explicit size or theme overrides.
+
+```mermaid
+flowchart LR
+    A[Open document] --> B[Read text]
+    B --> C[Inspect PNG]
+    C --> D[Inspect diagram]
+    D --> E[Increase viewing scale]
+    E --> F[Compare readability]
+```
+
+Reference sentence: Open the document, review the diagram, and check the result.
+
+## Manual comparison
+
+1. Open this file in QuickMD at the default viewing scale.
+2. Note the PNG width and Mermaid label size relative to the paragraphs.
+3. Increase the text size or zoom using the viewer's controls.
+4. Compare all four elements again without resizing the window.
+5. Return to the original scale and check that the appearance returns to baseline.
+6. Click the PNG, check that it fits the window, then press Escape to return.
+7. Click the Mermaid diagram, try its zoom controls, then click Done to return.
+
+Record which control you used and whether the PNG and diagram grew along with
+the text. If the viewer provides separate text-size and zoom controls, repeat
+the comparison for each.
+
+Graphics fit within the document column. Once they reach its width, click to
+open the larger preview. Reducing text size should shrink even a fitted graphic.
diff --git a/scripts/check-mermaid-scaling.swift b/scripts/check-mermaid-scaling.swift
new file mode 100644
index 0000000..0c63526
--- /dev/null
+++ b/scripts/check-mermaid-scaling.swift
@@ -0,0 +1,67 @@
+// Run from the repository root: swift scripts/check-mermaid-scaling.swift
+import AppKit
+import WebKit
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory)
+let resources = URL(fileURLWithPath: FileManager.default.currentDirectoryPath)
+    .appendingPathComponent("QuickMD/QuickMD/Resources")
+let web = WKWebView(frame: NSRect(x: 0, y: 0, width: 1400, height: 800))
+let window = NSWindow(contentRect: web.frame, styleMask: [.borderless], backing: .buffered, defer: false)
+window.contentView = web
+window.orderBack(nil)
+
+func js(_ code: String) async throws -> Any? {
+    try await web.evaluateJavaScript(code)
+}
+func pause() async throws { try await Task.sleep(nanoseconds: 100_000_000) }
+func width(scale: Double) async throws -> Double {
+    _ = try await js("renderDiagram('flowchart LR; A[Read text] --> B[Inspect image]', false, \(scale));")
+    for _ in 0..<100 {
+        if let value = try await js("document.querySelector('#output svg')?.getBoundingClientRect().width ?? 0") as? Double, value > 0 {
+            return value
+        }
+        try await pause()
+    }
+    throw NSError(domain: "Diagram did not render", code: 1)
+}
+Task { @MainActor in
+    do {
+        web.loadFileURL(resources.appendingPathComponent("mermaid-template.html"), allowingReadAccessTo: resources)
+        for _ in 0..<100 {
+            if (try? await js("typeof renderDiagram")) as? String == "function" { break }
+            try await pause()
+        }
+        let baseline = try await width(scale: 1)
+        let enlarged = try await width(scale: 1.5)
+        let reduced = try await width(scale: 0.75)
+        print("Mermaid widths: baseline=\(baseline), 150%=\(enlarged), 75%=\(reduced)")
+        guard abs(enlarged / baseline - 1.5) < 0.02,
+              abs(reduced / baseline - 0.75) < 0.02 else {
+            print("FAIL: diagram does not scale with text")
+            exit(1)
+        }
+        web.setFrameSize(NSSize(width: 200, height: 800))
+        try await pause()
+        let narrow = try await js("document.querySelector('#output svg').getBoundingClientRect().width") as! Double
+        guard narrow <= 201 else { print("FAIL: diagram exceeds column width"); exit(1) }
+        let narrowBaseline = try await width(scale: 1)
+        let narrowReduced = try await width(scale: 0.75)
+        guard abs(narrowReduced / narrowBaseline - 0.75) < 0.02 else {
+            print("FAIL: fitted diagram does not shrink in a narrow column"); exit(1)
+        }
+        _ = try await js("renderDiagram('flowchart TD; A[Read] --> B[Inspect]', false, 1, true);")
+        for _ in 0..<100 {
+            if (try await js("document.querySelector('#output svg') != null")) as? Bool == true { break }
+            try await pause()
+        }
+        let fitted = try await js("(() => { const r = document.querySelector('#output svg').getBoundingClientRect(); return [r.width, r.height]; })()") as! [Double]
+        guard fitted[0] <= 201, fitted[1] <= 801,
+              abs(fitted[0] - 200) < 1 || abs(fitted[1] - 800) < 1 else {
+            print("FAIL: preview does not fit the window"); exit(1)
+        }
+        print("PASS: proportional scaling, narrow-column shrinking, and preview fit")
+        exit(0)
+    } catch { print("FAIL: \(error)"); exit(1) }
+}
+app.run()