diff --git a/src/App.tsx b/src/App.tsx
index a28b62f..a820019 100644
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -71,6 +71,7 @@ import { useLocalStorage } from '@/hooks/useLocalStorage'
 import { useDebouncedValue } from '@/hooks/useDebouncedValue'
 import { useMediaQuery } from '@/hooks/useMediaQuery'
 import { useDocumentLibrary } from '@/hooks/useDocumentLibrary'
+import { useScrollSync } from '@/hooks/useScrollSync'
 
 import { DEFAULT_CONFIG, MARGIN_PRESETS, STORAGE_KEYS } from '@/lib/constants'
 import { countHeadings } from '@/lib/utils'
@@ -172,7 +173,7 @@ export default function App({ lock }: AppProps) {
   const [saving, setSaving] = useState(false)
 
   const [editorView, setEditorView] = useState<EditorView | null>(null)
-  const [editorScroll, setEditorScroll] = useState<number | undefined>(undefined)
+  const [previewScrollEl, setPreviewScrollEl] = useState<HTMLElement | null>(null)
   const previewRef = useRef<PreviewHandle>(null)
   const fileInputRef = useRef<HTMLInputElement>(null)
   const mainRef = useRef<HTMLDivElement>(null)
@@ -203,6 +204,17 @@ export default function App({ lock }: AppProps) {
   const showPreview = effectiveView !== 'editor'
   const isSplit = showEditor && showPreview && isDesktop
 
+  // Anchor-based scroll sync between the editor and preview (split view only).
+  const [syncEnabled, setSyncEnabled] = useLocalStorage('scripto:scroll-sync', true)
+  const getDoc = useCallback(() => previewRef.current?.getDocElement() ?? null, [])
+  useScrollSync({
+    view: editorView,
+    previewScroll: previewScrollEl,
+    getPreviewDoc: getDoc,
+    bodyLineOffset: parsed.bodyLineOffset,
+    enabled: syncEnabled && isSplit,
+  })
+
   const startResize = useCallback(
     (event: React.MouseEvent) => {
       event.preventDefault()
@@ -301,7 +313,6 @@ export default function App({ lock }: AppProps) {
     [library, t],
   )
 
-  const getDoc = useCallback(() => previewRef.current?.getDocElement() ?? null, [])
   const handleEditorError = useCallback((message: string) => toast.error(message), [])
 
   const ensureDoc = useCallback((): HTMLElement | null => {
@@ -893,7 +904,6 @@ export default function App({ lock }: AppProps) {
               resolvedTheme={resolvedTheme}
               direction={effectiveConfig.direction === 'auto' ? ui.dir : effectiveConfig.direction}
               onReady={setEditorView}
-              onScrollFraction={showPreview ? setEditorScroll : undefined}
               onActivity={bumpActivity}
               slashAi={handleAiAction}
               onSlashHelp={openFormattingHelp}
@@ -949,7 +959,9 @@ export default function App({ lock }: AppProps) {
               content={parsed.body}
               config={effectiveConfig}
               resolvedTheme={resolvedTheme}
-              scrollFraction={editorScroll}
+              onScrollElement={setPreviewScrollEl}
+              syncEnabled={isSplit ? syncEnabled : undefined}
+              onToggleSync={isSplit ? () => setSyncEnabled((v) => !v) : undefined}
             />
           )}
         </section>
diff --git a/src/components/editor/MarkdownEditor.tsx b/src/components/editor/MarkdownEditor.tsx
index 9a05018..74666ba 100644
--- a/src/components/editor/MarkdownEditor.tsx
+++ b/src/components/editor/MarkdownEditor.tsx
@@ -23,7 +23,6 @@ interface MarkdownEditorProps {
   onReady?: (view: EditorView) => void
   wordWrap?: boolean
   direction?: TextDirection
-  onScrollFraction?: (fraction: number) => void
   /** Fires on any selection / geometry / scroll change so overlays can reposition. */
   onActivity?: () => void
   /** Enables the `/` slash menu, routing AI items to this handler. */
@@ -115,7 +114,6 @@ export function MarkdownEditor({
   onReady,
   wordWrap = true,
   direction = 'auto',
-  onScrollFraction,
   onActivity,
   slashAi,
   onSlashHelp,
@@ -129,7 +127,6 @@ export function MarkdownEditor({
   const callbacks = useRef({
     onChange,
     onReady,
-    onScrollFraction,
     onActivity,
     slashAi,
     onSlashHelp,
@@ -140,7 +137,6 @@ export function MarkdownEditor({
   callbacks.current = {
     onChange,
     onReady,
-    onScrollFraction,
     onActivity,
     slashAi,
     onSlashHelp,
@@ -226,13 +222,8 @@ export function MarkdownEditor({
 
     base.push(
       EditorView.domEventHandlers({
-        scroll: (_event, view) => {
+        scroll: () => {
           callbacks.current.onActivity?.()
-          const notify = callbacks.current.onScrollFraction
-          if (!notify) return
-          const el = view.scrollDOM
-          const max = el.scrollHeight - el.clientHeight
-          notify(max > 0 ? el.scrollTop / max : 0)
         },
         paste: (event, view) => {
           const files = imageFiles(event.clipboardData?.files)
diff --git a/src/components/preview/Preview.tsx b/src/components/preview/Preview.tsx
index 433671f..fe6b692 100644
--- a/src/components/preview/Preview.tsx
+++ b/src/components/preview/Preview.tsx
@@ -8,7 +8,7 @@ import {
   useState,
   type CSSProperties,
 } from 'react'
-import { Eye, EyeOff, Minus, Plus } from 'lucide-react'
+import { Eye, EyeOff, Link2, Link2Off, Minus, Plus } from 'lucide-react'
 import { MarkdownRenderer } from '@/markdown/MarkdownRenderer'
 import { ErrorBoundary } from '@/components/ErrorBoundary'
 import { useLanguage } from '@/i18n'
@@ -25,15 +25,17 @@ import type { PdfConfig, ResolvedTheme, TocEntry } from '@/types'
 export interface PreviewHandle {
   /** The live document element — cloned by the PDF engine for export. */
   getDocElement: () => HTMLElement | null
-  scrollToFraction: (fraction: number) => void
 }
 
 interface PreviewProps {
   content: string
   config: PdfConfig
   resolvedTheme: ResolvedTheme
-  scrollFraction?: number
-  onScrollFraction?: (fraction: number) => void
+  /** Reports the scroll container up (for scroll sync); null on unmount. */
+  onScrollElement?: (el: HTMLElement | null) => void
+  /** Scroll-sync toggle — rendered only when provided (i.e. in split view). */
+  syncEnabled?: boolean
+  onToggleSync?: () => void
 }
 
 const pageCard = 'rounded-xl bg-surface shadow-sm ring-1 ring-border/60'
@@ -41,13 +43,12 @@ const pageCard = 'rounded-xl bg-surface shadow-sm ring-1 ring-border/60'
 /** The live, scrollable rendered document. Shows the same cover + contents pages
  * the PDF will, so the preview matches the export. */
 export const Preview = forwardRef<PreviewHandle, PreviewProps>(function Preview(
-  { content, config, resolvedTheme, scrollFraction, onScrollFraction },
+  { content, config, resolvedTheme, onScrollElement, syncEnabled, onToggleSync },
   ref,
 ) {
   const { t, lang } = useLanguage()
   const scrollRef = useRef<HTMLDivElement>(null)
   const docRef = useRef<HTMLDivElement>(null)
-  const syncingRef = useRef(false)
   const [progress, setProgress] = useState(0)
   const [zoom, setZoom] = useState(1)
   const zoomRef = useRef(1)
@@ -59,23 +60,14 @@ export const Preview = forwardRef<PreviewHandle, PreviewProps>(function Preview(
 
   useImperativeHandle(ref, () => ({
     getDocElement: () => docRef.current,
-    scrollToFraction: (fraction) => {
-      const el = scrollRef.current
-      if (!el) return
-      const max = el.scrollHeight - el.clientHeight
-      el.scrollTop = max * fraction
-    },
   }))
 
+  // Report the scroll container to the parent so the scroll-sync hook can wire
+  // native listeners to it.
   useEffect(() => {
-    const el = scrollRef.current
-    if (!el || scrollFraction === undefined) return
-    syncingRef.current = true
-    const max = el.scrollHeight - el.clientHeight
-    el.scrollTop = max * scrollFraction
-    const id = window.setTimeout(() => (syncingRef.current = false), 60)
-    return () => window.clearTimeout(id)
-  }, [scrollFraction])
+    onScrollElement?.(scrollRef.current)
+    return () => onScrollElement?.(null)
+  }, [onScrollElement])
 
   // Pinch-to-zoom the preview on touch devices (native non-passive listeners so
   // the gesture can preventDefault the browser's own page zoom).
@@ -161,10 +153,7 @@ export const Preview = forwardRef<PreviewHandle, PreviewProps>(function Preview(
         onScroll={(e) => {
           const el = e.currentTarget
           const max = el.scrollHeight - el.clientHeight
-          const fraction = max > 0 ? el.scrollTop / max : 0
-          setProgress(fraction)
-          if (syncingRef.current || !onScrollFraction) return
-          onScrollFraction(fraction)
+          setProgress(max > 0 ? el.scrollTop / max : 0)
         }}
       >
         <div
@@ -223,6 +212,24 @@ export const Preview = forwardRef<PreviewHandle, PreviewProps>(function Preview(
         </div>
       </div>
 
+      {/* Scroll-sync toggle — only in split view (when the editor is visible). */}
+      {onToggleSync && (
+        <button
+          type="button"
+          onClick={onToggleSync}
+          aria-pressed={syncEnabled}
+          title={syncEnabled ? t('preview.sync.on') : t('preview.sync.off')}
+          aria-label={syncEnabled ? t('preview.sync.on') : t('preview.sync.off')}
+          className={`absolute end-3 top-3 z-20 flex h-8 w-8 items-center justify-center rounded-full border shadow-lg backdrop-blur transition-colors ${
+            syncEnabled
+              ? 'border-primary/30 bg-primary/10 text-primary'
+              : 'border-border bg-surface/90 text-muted-foreground hover:bg-muted hover:text-foreground'
+          }`}
+        >
+          {syncEnabled ? <Link2 size={15} /> : <Link2Off size={15} />}
+        </button>
+      )}
+
       {/* Floating zoom control — most useful on touch / small screens. */}
       <div className="absolute bottom-3 end-3 z-20 flex items-center gap-0.5 rounded-full border border-border bg-surface/90 p-0.5 shadow-lg backdrop-blur lg:hidden">
         <button
diff --git a/src/hooks/useScrollSync.ts b/src/hooks/useScrollSync.ts
new file mode 100644
index 0000000..d707044
--- /dev/null
+++ b/src/hooks/useScrollSync.ts
@@ -0,0 +1,194 @@
+import { useEffect } from 'react'
+import type { EditorView } from '@codemirror/view'
+
+interface ScrollSyncOptions {
+  /** The CodeMirror editor, once ready. */
+  view: EditorView | null
+  /** The preview's scrolling element. */
+  previewScroll: HTMLElement | null
+  /** Returns the rendered document root (holds the `data-source-line` anchors). */
+  getPreviewDoc: () => HTMLElement | null
+  /** Editor lines before the body starts (front-matter height). */
+  bodyLineOffset: number
+  /** Master switch — sync only runs in split view when the user enables it. */
+  enabled: boolean
+}
+
+interface Anchor {
+  line: number
+  top: number
+}
+
+/** Idle window after the last user scroll input before the driver is released. */
+const DRIVER_IDLE_MS = 260
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(max, Math.max(min, value))
+
+/** Fractional source line at the editor's viewport top (full-document lines). */
+function editorTopLine(view: EditorView): number {
+  const localY = view.scrollDOM.getBoundingClientRect().top - view.documentTop
+  const block = view.lineBlockAtHeight(localY)
+  const line = view.state.doc.lineAt(block.from).number
+  const frac = block.height > 0 ? (localY - block.top) / block.height : 0
+  return line + clamp(frac, 0, 1)
+}
+
+/** Scroll the editor so full-document line `target` sits at its viewport top. */
+function scrollEditorToLine(view: EditorView, target: number): void {
+  const lineNo = clamp(Math.floor(target), 1, view.state.doc.lines)
+  const frac = target - lineNo
+  const block = view.lineBlockAt(view.state.doc.line(lineNo).from)
+  const localY = block.top + frac * block.height
+  const screenTop = localY + view.documentTop
+  view.scrollDOM.scrollTop += screenTop - view.scrollDOM.getBoundingClientRect().top
+}
+
+/** Read the preview's `data-source-line` anchors as screen-space tops, sorted. */
+function readAnchors(doc: HTMLElement): Anchor[] {
+  const nodes = doc.querySelectorAll<HTMLElement>('[data-source-line]')
+  const anchors: Anchor[] = []
+  for (const node of nodes) {
+    const line = Number(node.getAttribute('data-source-line'))
+    if (!Number.isFinite(line)) continue
+    anchors.push({ line, top: node.getBoundingClientRect().top })
+  }
+  anchors.sort((a, b) => a.top - b.top)
+  return anchors
+}
+
+/** Find the two anchors bracketing a screen Y (or a value between their lines). */
+function bracketByTop(anchors: Anchor[], y: number): [Anchor, Anchor] | null {
+  if (anchors.length === 0) return null
+  if (y <= anchors[0].top) return [anchors[0], anchors[0]]
+  const last = anchors[anchors.length - 1]
+  if (y >= last.top) return [last, last]
+  for (let i = 0; i < anchors.length - 1; i++) {
+    if (y >= anchors[i].top && y < anchors[i + 1].top) return [anchors[i], anchors[i + 1]]
+  }
+  return [last, last]
+}
+
+function bracketByLine(anchors: Anchor[], line: number): [Anchor, Anchor] | null {
+  if (anchors.length === 0) return null
+  if (line <= anchors[0].line) return [anchors[0], anchors[0]]
+  const last = anchors[anchors.length - 1]
+  if (line >= last.line) return [last, last]
+  for (let i = 0; i < anchors.length - 1; i++) {
+    if (line >= anchors[i].line && line < anchors[i + 1].line) return [anchors[i], anchors[i + 1]]
+  }
+  return [last, last]
+}
+
+/** Fractional body source line at the preview's viewport top. */
+function previewTopLine(scroll: HTMLElement, anchors: Anchor[]): number | null {
+  const bracket = bracketByTop(anchors, scroll.getBoundingClientRect().top)
+  if (!bracket) return null
+  const [a, b] = bracket
+  if (a === b || b.top === a.top) return a.line
+  const t = (scroll.getBoundingClientRect().top - a.top) / (b.top - a.top)
+  return a.line + t * (b.line - a.line)
+}
+
+/** Scroll the preview so body source line `target` sits at its viewport top. */
+function scrollPreviewToLine(scroll: HTMLElement, anchors: Anchor[], target: number): void {
+  const bracket = bracketByLine(anchors, target)
+  if (!bracket) return
+  const [a, b] = bracket
+  const targetTop =
+    a === b || b.line === a.line
+      ? a.top
+      : a.top + ((target - a.line) / (b.line - a.line)) * (b.top - a.top)
+  scroll.scrollTop += targetTop - scroll.getBoundingClientRect().top
+}
+
+/**
+ * Bidirectional scroll sync between the CodeMirror editor and the rendered
+ * preview, keyed on Markdown source lines (see rehypeSourceLine). The pane the
+ * user is physically scrolling is the "driver"; the other follows. Programmatic
+ * follower scrolls never bounce back because only real input (wheel/touch/
+ * pointer/keys) claims the driver role.
+ */
+export function useScrollSync({
+  view,
+  previewScroll,
+  getPreviewDoc,
+  bodyLineOffset,
+  enabled,
+}: ScrollSyncOptions): void {
+  useEffect(() => {
+    if (!enabled || !view || !previewScroll) return
+    const editorScroll = view.scrollDOM
+
+    let driver: 'editor' | 'preview' | null = null
+    let idleTimer = 0
+    let frame = 0
+
+    const releaseSoon = () => {
+      window.clearTimeout(idleTimer)
+      idleTimer = window.setTimeout(() => {
+        driver = null
+      }, DRIVER_IDLE_MS)
+    }
+    const claim = (who: 'editor' | 'preview') => {
+      driver = who
+      releaseSoon()
+    }
+
+    const syncFromEditor = () => {
+      const doc = getPreviewDoc()
+      if (!doc) return
+      const editorLine = editorTopLine(view)
+      const bodyLine = editorLine - bodyLineOffset
+      scrollPreviewToLine(previewScroll, readAnchors(doc), bodyLine)
+    }
+    const syncFromPreview = () => {
+      const doc = getPreviewDoc()
+      if (!doc) return
+      const bodyLine = previewTopLine(previewScroll, readAnchors(doc))
+      if (bodyLine == null) return
+      scrollEditorToLine(view, bodyLine + bodyLineOffset)
+    }
+
+    const onEditorScroll = () => {
+      if (driver !== 'editor') return
+      releaseSoon()
+      if (frame) return
+      frame = window.requestAnimationFrame(() => {
+        frame = 0
+        syncFromEditor()
+      })
+    }
+    const onPreviewScroll = () => {
+      if (driver !== 'preview') return
+      releaseSoon()
+      if (frame) return
+      frame = window.requestAnimationFrame(() => {
+        frame = 0
+        syncFromPreview()
+      })
+    }
+
+    const editorInput = () => claim('editor')
+    const previewInput = () => claim('preview')
+    const inputEvents = ['wheel', 'touchstart', 'pointerdown', 'keydown'] as const
+
+    for (const type of inputEvents) {
+      editorScroll.addEventListener(type, editorInput, { passive: true })
+      previewScroll.addEventListener(type, previewInput, { passive: true })
+    }
+    editorScroll.addEventListener('scroll', onEditorScroll, { passive: true })
+    previewScroll.addEventListener('scroll', onPreviewScroll, { passive: true })
+
+    return () => {
+      window.clearTimeout(idleTimer)
+      if (frame) window.cancelAnimationFrame(frame)
+      for (const type of inputEvents) {
+        editorScroll.removeEventListener(type, editorInput)
+        previewScroll.removeEventListener(type, previewInput)
+      }
+      editorScroll.removeEventListener('scroll', onEditorScroll)
+      previewScroll.removeEventListener('scroll', onPreviewScroll)
+    }
+  }, [enabled, view, previewScroll, getPreviewDoc, bodyLineOffset])
+}
diff --git a/src/lib/frontmatter.ts b/src/lib/frontmatter.ts
index dcc5871..7fb2086 100644
--- a/src/lib/frontmatter.ts
+++ b/src/lib/frontmatter.ts
@@ -19,25 +19,36 @@ export interface ParsedDocument {
   body: string
   /** Whether a front-matter block was found. */
   hasFrontmatter: boolean
+  /** Editor source lines before the body starts (0 when no front-matter).
+   * Body line N corresponds to editor line N + bodyLineOffset. */
+  bodyLineOffset: number
 }
 
 const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n---\r?\n?/
 
+/** Lines consumed by the matched front-matter block (its newline count). */
+const countLines = (block: string): number => (block.match(/\r?\n/g)?.length ?? 0)
+
 /**
  * Split a YAML front-matter block (`--- … ---`) from the Markdown body.
  * Front-matter is never shown in the preview but drives document metadata.
  */
 export function parseFrontmatter(source: string): ParsedDocument {
   const match = FRONTMATTER_RE.exec(source)
-  if (!match) return { data: {}, body: source, hasFrontmatter: false }
+  if (!match) return { data: {}, body: source, hasFrontmatter: false, bodyLineOffset: 0 }
 
   try {
     const parsed = yaml.load(match[1])
     const data = parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {}
-    return { data, body: source.slice(match[0].length), hasFrontmatter: true }
+    return {
+      data,
+      body: source.slice(match[0].length),
+      hasFrontmatter: true,
+      bodyLineOffset: countLines(match[0]),
+    }
   } catch (error) {
     logger.warn('Invalid YAML front-matter; ignoring', error)
-    return { data: {}, body: source, hasFrontmatter: false }
+    return { data: {}, body: source, hasFrontmatter: false, bodyLineOffset: 0 }
   }
 }
 
diff --git a/src/lib/i18n.ts b/src/lib/i18n.ts
index e62a5d0..0c1fcd7 100644
--- a/src/lib/i18n.ts
+++ b/src/lib/i18n.ts
@@ -803,6 +803,8 @@ export const EN_STRINGS = {
 
   // Preview cover/Contents toggle
   'preview.frontMatter.toggle': 'Show cover & contents',
+  'preview.sync.on': 'Scroll sync on — click to disable',
+  'preview.sync.off': 'Scroll sync off — click to enable',
   'print.frontMatter': 'Cover & contents',
 
   // Cover page & contents
@@ -1592,6 +1594,8 @@ export const STRINGS: Record<UiLanguage, Dictionary> = {
 
     // Preview cover/Contents toggle
     'preview.frontMatter.toggle': 'إظهار الغلاف والمحتويات',
+    'preview.sync.on': 'مزامنة التمرير مُفعّلة — انقر للتعطيل',
+    'preview.sync.off': 'مزامنة التمرير مُعطّلة — انقر للتفعيل',
     'print.frontMatter': 'الغلاف والمحتويات',
 
     // Cover page & contents
diff --git a/src/markdown/MarkdownRenderer.tsx b/src/markdown/MarkdownRenderer.tsx
index f4ff2b9..81f049c 100644
--- a/src/markdown/MarkdownRenderer.tsx
+++ b/src/markdown/MarkdownRenderer.tsx
@@ -10,6 +10,7 @@ import rehypeRaw from 'rehype-raw'
 import rehypeKatex from 'rehype-katex'
 import rehypeSlug from 'rehype-slug'
 import rehypePrismPlus from 'rehype-prism-plus'
+import { rehypeSourceLine } from './plugins/rehypeSourceLine'
 import { remarkCallouts } from './plugins/remarkCallouts'
 import { remarkMarks } from './plugins/remarkMarks'
 import { CodeBlock } from './components/CodeBlock'
@@ -65,6 +66,9 @@ const remarkPlugins = [
 ] as const
 
 const rehypePlugins = [
+  // First, while mdast positions are intact, so scroll-sync anchors survive
+  // rehype-raw's reserialization of raw HTML.
+  rehypeSourceLine,
   rehypeRaw,
   rehypeKatex,
   rehypeSlug,
diff --git a/src/markdown/plugins/rehypeSourceLine.ts b/src/markdown/plugins/rehypeSourceLine.ts
new file mode 100644
index 0000000..6f8b0ea
--- /dev/null
+++ b/src/markdown/plugins/rehypeSourceLine.ts
@@ -0,0 +1,54 @@
+import { visit } from 'unist-util-visit'
+import type { Element, Root } from 'hast'
+
+/**
+ * Block-level tags worth anchoring for scroll sync. Inline tags are skipped so
+ * the preview only carries a manageable set of `data-source-line` anchors.
+ */
+const BLOCK_TAGS = new Set([
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'ul',
+  'ol',
+  'li',
+  'blockquote',
+  'pre',
+  'table',
+  'tr',
+  'hr',
+  'img',
+  'figure',
+  'dl',
+  'dt',
+  'dd',
+  'section',
+  'div',
+])
+
+/**
+ * Stamps each block element with `data-source-line` (the 1-based Markdown
+ * source line it originated from). The scroll-sync hook maps between editor
+ * lines and these anchors so the same paragraph stays aligned across panes,
+ * regardless of how tall each side renders it.
+ *
+ * Runs first in the rehype pipeline so positions are still intact (before
+ * rehype-raw reserializes raw HTML). The attribute is invisible, has no layout
+ * effect, and is dropped from the PDF export clone.
+ */
+export function rehypeSourceLine() {
+  return (tree: Root): void => {
+    visit(tree, 'element', (node: Element) => {
+      const line = node.position?.start?.line
+      if (line == null || !BLOCK_TAGS.has(node.tagName)) return
+      node.properties = node.properties ?? {}
+      if (node.properties['dataSourceLine'] == null) {
+        node.properties['dataSourceLine'] = String(line)
+      }
+    })
+  }
+}
diff --git a/src/pdf/pageStyles.ts b/src/pdf/pageStyles.ts
index e764888..9051a23 100644
--- a/src/pdf/pageStyles.ts
+++ b/src/pdf/pageStyles.ts
@@ -107,6 +107,23 @@ export function buildPageCss(config: PdfConfig): string {
     .scripto-doc .katex-display, .scripto-doc .mermaid-figure {
       break-inside: avoid;
     }
+
+    /* Tall diagrams / images are scaled to fit within one page's content box,
+       WITH the heading that precedes them (headings set break-after: avoid). An
+       unbreakable heading+figure taller than the page makes Paged.js split the
+       SVG — spilling blank pages and leaking the diagram's inner <style> as
+       text — so the cap reserves room for a heading + the figure's margins.
+       width:auto keeps the aspect ratio intact. */
+    .scripto-doc .mermaid-figure svg,
+    .scripto-doc figure svg,
+    .scripto-doc img {
+      max-height: ${round(Math.max(40, height - top - bottom - 30))}mm;
+    }
+    .scripto-doc .mermaid-figure svg,
+    .scripto-doc figure svg {
+      width: auto;
+      height: auto;
+    }
     /* Tables flow across pages: header repeats, rows never split. */
     .scripto-doc .table-wrap { break-inside: auto; overflow: visible; border: none; }
     .scripto-doc table { break-inside: auto; }