Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): unclamp Mermaid zoom for large diagrams (PRD-8202) (#3744)

Abraham40b4a22767bc
diff --git a/.changeset/prd-8202-mermaid-zoom-fit-compensated.md b/.changeset/prd-8202-mermaid-zoom-fit-compensated.md
new file mode 100644
index 000000000..85c766a3e
--- /dev/null
+++ b/.changeset/prd-8202-mermaid-zoom-fit-compensated.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Zoom-in on a large Mermaid diagram can now reach 1:1 and past it. Panzoom's `maxScale` was a multiplier on the SVG's already-fit painted size, so a diagram that mermaid shrank to fit the container capped below its natural size. The Mermaid host now divides the ceiling by the fit ratio, so `MERMAID_ZOOM_MAX` behaves as "max natural zoom" regardless of the diagram's size.
diff --git a/packages/app/src/editor/components/Mermaid.test.tsx b/packages/app/src/editor/components/Mermaid.test.tsx
index 738c253a2..1f8d20701 100644
--- a/packages/app/src/editor/components/Mermaid.test.tsx
+++ b/packages/app/src/editor/components/Mermaid.test.tsx
@@ -22,7 +22,7 @@ vi.doMock('@lingui/react/macro', () => ({
useLingui: () => ({ t: renderLinguiTemplate }),
}));
-const { MermaidView } = await import('./Mermaid.tsx');
+const { MermaidView, compensatedMaxScale } = await import('./Mermaid.tsx');
describe('MermaidView — placeholder branch', () => {
test('empty chart renders the placeholder shell with real height', () => {
@@ -58,3 +58,24 @@ describe('MermaidView — pre-render mount state', () => {
expect(html).toContain('mermaid-rendering');
});
});
+
+describe('compensatedMaxScale', () => {
+ test('returns the raw MERMAID_ZOOM_MAX floor when the diagram paints at or above natural size', () => {
+ expect(compensatedMaxScale(500, 500)).toBe(4);
+ expect(compensatedMaxScale(1000, 500)).toBe(4);
+ });
+
+ test('compensates a fit-shrunk diagram so it can still reach the intended natural-size multiple', () => {
+ // A 2000-wide viewBox rendered at 500 CSS pixels sits at 0.25× on screen.
+ // MERMAID_ZOOM_MAX (4) means "4× natural" — Panzoom must reach scale 16.
+ expect(compensatedMaxScale(500, 2000)).toBe(16);
+ // 0.5× fit → 2× the floor.
+ expect(compensatedMaxScale(1000, 2000)).toBe(8);
+ });
+
+ test('falls back to the raw floor for degenerate inputs', () => {
+ expect(compensatedMaxScale(0, 500)).toBe(4);
+ expect(compensatedMaxScale(500, 0)).toBe(4);
+ expect(compensatedMaxScale(-5, 500)).toBe(4);
+ });
+});
diff --git a/packages/app/src/editor/components/Mermaid.tsx b/packages/app/src/editor/components/Mermaid.tsx
index 17752cecf..b9620d8cd 100644
--- a/packages/app/src/editor/components/Mermaid.tsx
+++ b/packages/app/src/editor/components/Mermaid.tsx
@@ -97,6 +97,21 @@ interface RenderState {
const MERMAID_ZOOM_MIN = 0.5;
const MERMAID_ZOOM_MAX = 4;
const MERMAID_ZOOM_STEP = 0.25;
+
+/**
+ * Compensate Panzoom's `maxScale` so it caps zoom relative to the SVG's
+ * natural (viewBox) size, not its fit-shrunk painted size. Given `MERMAID_ZOOM_MAX`
+ * as the "max multiple of natural size" intent, a fit-shrunk diagram
+ * (`paintedWidth < viewBoxWidth`) needs a proportionally larger `maxScale`
+ * so the user can still zoom to `MERMAID_ZOOM_MAX * natural`. Diagrams that
+ * paint at or above natural size keep the raw `MERMAID_ZOOM_MAX` floor.
+ */
+export function compensatedMaxScale(paintedWidth: number, viewBoxWidth: number): number {
+ if (viewBoxWidth <= 0 || paintedWidth <= 0) return MERMAID_ZOOM_MAX;
+ const displayScale = paintedWidth / viewBoxWidth;
+ return Math.max(MERMAID_ZOOM_MAX, MERMAID_ZOOM_MAX / displayScale);
+}
+
const MERMAID_PAN_STEP = 48;
const MERMAID_PAN_ANIMATE_MS = 200;
const MERMAID_PAN_EASING = 'ease-out';
@@ -335,6 +350,7 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
const editorRef = useRef<MermaidWysiwygEditor | null>(null);
const viewRef = useRef<MermaidCanvasView | null>(null);
const panzoomRef = useRef<PanzoomObject | null>(null);
+ const maxScaleObsRef = useRef<ResizeObserver | null>(null);
const loadFailedRef = useRef(false);
const hasChart = Boolean(chart.trim());
@@ -420,6 +436,38 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
touchAction: 'auto',
});
panzoomRef.current = panzoom;
+ maxScaleObsRef.current?.disconnect();
+ maxScaleObsRef.current = null;
+ if (viewBox && viewBox.width > 0) {
+ const vbW = viewBox.width;
+ // `getBoundingClientRect().width` is transform-inclusive, so
+ // measuring it AFTER the user has zoomed would fold the zoom
+ // factor into `displayScale` and re-introduce the bug this
+ // compensation exists to solve. The initial call runs right
+ // after Panzoom mounts (no transform yet) so bounding-rect is
+ // fine; the ResizeObserver callback reads `contentRect.width`
+ // instead — untransformed content box.
+ const applyMaxScale = (width: number) => {
+ if (disposed || panzoomRef.current !== panzoom) return;
+ if (width <= 0) return;
+ try {
+ panzoom.setOptions({
+ maxScale: compensatedMaxScale(width, vbW),
+ });
+ } catch (err) {
+ console.warn('[Mermaid] maxScale compensation failed:', err);
+ }
+ };
+ applyMaxScale(svgElement.getBoundingClientRect().width);
+ if (typeof ResizeObserver !== 'undefined') {
+ const ro = new ResizeObserver((entries) => {
+ const width = entries[0]?.contentRect.width ?? 0;
+ applyMaxScale(width);
+ });
+ ro.observe(svgElement);
+ maxScaleObsRef.current = ro;
+ }
+ }
})
.catch((err) => {
console.warn('[Mermaid] panzoom setup failed:', err);
@@ -509,6 +557,8 @@ export function MermaidView({ chart = '', className, editBinding }: MermaidProps
for (const off of offs) off();
panzoomRef.current?.destroy();
panzoomRef.current = null;
+ maxScaleObsRef.current?.disconnect();
+ maxScaleObsRef.current = null;
view?.destroy();
editorRef.current = null;
viewRef.current = null;