md2ui 1.0.19 → 1.0.21

package/src/components/ImageZoom.vue

@@ -77,8 +77,9 @@
 </template>
 
 <script setup>
-import { ref, computed, nextTick, watch } from 'vue'
+import { ref, computed, nextTick, watch, onMounted, onBeforeUnmount } from 'vue'
 import { ZoomIn, ZoomOut, RotateCcw, X, ChevronLeft, ChevronRight, Copy, Check } from 'lucide-vue-next'
+import { imgToPngBlob, svgToPngBlob } from '../utils/imageConverter.js'
 
 // Props
 const props = defineProps({
@@ -181,7 +182,6 @@ async function handleCopyImage() {
 
     let blobPromise
     if (img) {
-      // 构造 PNG blob Promise
       blobPromise = imgToPngBlob(img.src)
     } else if (svg) {
       blobPromise = svgToPngBlob(svg, 2)
@@ -200,124 +200,6 @@ async function handleCopyImage() {
   }
 }
 
-// 将图片 URL 转为 PNG blob（兼容同源和跨域）
-async function imgToPngBlob(src) {
-  // 策略1：fetch 获取（同源图片直接成功）
-  try {
-    const resp = await fetch(src)
-    const blob = await resp.blob()
-    if (blob.type === 'image/png') return blob
-    return blobToCanvasPng(blob, 1)
-  } catch {
-    // 策略2：通过 crossOrigin Image 加载（需服务器支持 CORS）
-    try {
-      return await loadImageToBlob(src, true)
-    } catch {
-      // 策略3：不设 crossOrigin 直接画（可能被 taint，但对某些场景有效）
-      return loadImageToBlob(src, false)
-    }
-  }
-}
-
-// 加载图片到 canvas 并转 PNG blob
-function loadImageToBlob(src, useCors) {
-  return new Promise((resolve, reject) => {
-    const image = new Image()
-    if (useCors) image.crossOrigin = 'anonymous'
-    image.onload = () => {
-      try {
-        const canvas = document.createElement('canvas')
-        canvas.width = image.naturalWidth
-        canvas.height = image.naturalHeight
-        canvas.getContext('2d').drawImage(image, 0, 0)
-        canvas.toBlob(b => b ? resolve(b) : reject(new Error('toBlob null')), 'image/png')
-      } catch (e) {
-        reject(e)
-      }
-    }
-    image.onerror = () => reject(new Error('图片加载失败'))
-    image.src = src
-  })
-}
-
-// 将任意图片 blob 通过 canvas 转为 PNG blob
-function blobToCanvasPng(srcBlob, scale = 1) {
-  return new Promise((resolve, reject) => {
-    const url = URL.createObjectURL(srcBlob)
-    const image = new Image()
-    image.onload = () => {
-      const canvas = document.createElement('canvas')
-      canvas.width = image.naturalWidth * scale
-      canvas.height = image.naturalHeight * scale
-      const ctx = canvas.getContext('2d')
-      if (scale !== 1) ctx.scale(scale, scale)
-      ctx.drawImage(image, 0, 0)
-      URL.revokeObjectURL(url)
-      canvas.toBlob(b => resolve(b), 'image/png')
-    }
-    image.onerror = () => { URL.revokeObjectURL(url); reject(new Error('图片加载失败')) }
-    image.src = url
-  })
-}
-
-// SVG 转 PNG blob（处理 foreignObject 导致的 tainted canvas 问题）
-function svgToPngBlob(svgEl, scale = 2) {
-  return new Promise((resolve, reject) => {
-    const clone = svgEl.cloneNode(true)
-    // 从 viewBox 或属性中获取 SVG 实际尺寸，确保复制完整
-    const viewBox = clone.getAttribute('viewBox')
-    let svgWidth, svgHeight
-    if (viewBox) {
-      const parts = viewBox.split(/[\s,]+/)
-      svgWidth = parseFloat(parts[2])
-      svgHeight = parseFloat(parts[3])
-    }
-    // 回退到 width/height 属性或 getBoundingClientRect
-    if (!svgWidth || !svgHeight) {
-      svgWidth = parseFloat(clone.getAttribute('width')) || svgEl.getBoundingClientRect().width || 800
-      svgHeight = parseFloat(clone.getAttribute('height')) || svgEl.getBoundingClientRect().height || 600
-    }
-    // 显式设置 width/height 属性，确保 Image 加载时尺寸正确
-    clone.setAttribute('width', svgWidth)
-    clone.setAttribute('height', svgHeight)
-    // 将 foreignObject 替换为 text 元素，避免 canvas 被污染
-    clone.querySelectorAll('foreignObject').forEach(fo => {
-      const text = fo.textContent.trim()
-      const x = fo.getAttribute('x') || '0'
-      const y = fo.getAttribute('y') || '0'
-      const width = fo.getAttribute('width') || '100'
-      const height = fo.getAttribute('height') || '20'
-      const textEl = document.createElementNS('http://www.w3.org/2000/svg', 'text')
-      textEl.setAttribute('x', String(parseFloat(x) + parseFloat(width) / 2))
-      textEl.setAttribute('y', String(parseFloat(y) + parseFloat(height) / 2 + 5))
-      textEl.setAttribute('text-anchor', 'middle')
-      textEl.setAttribute('font-size', '14')
-      textEl.setAttribute('fill', '#455a64')
-      textEl.textContent = text
-      fo.parentNode.replaceChild(textEl, fo)
-    })
-    const svgData = new XMLSerializer().serializeToString(clone)
-    const svgBlob = new Blob([svgData], { type: 'image/svg+xml;charset=utf-8' })
-    const url = URL.createObjectURL(svgBlob)
-    const image = new Image()
-    image.onload = () => {
-      // 使用从 SVG 提取的精确尺寸，而非 naturalWidth/Height（后者对无 width/height 的 SVG 不可靠）
-      const w = svgWidth * scale
-      const h = svgHeight * scale
-      const canvas = document.createElement('canvas')
-      canvas.width = w
-      canvas.height = h
-      const ctx = canvas.getContext('2d')
-      ctx.scale(scale, scale)
-      ctx.drawImage(image, 0, 0, svgWidth, svgHeight)
-      URL.revokeObjectURL(url)
-      canvas.toBlob(b => b ? resolve(b) : reject(new Error('toBlob null')), 'image/png')
-    }
-    image.onerror = () => { URL.revokeObjectURL(url); reject(new Error('SVG加载失败')) }
-    image.src = url
-  })
-}
-
 // 处理遮罩层点击
 function handleOverlayClick(event) {
   if (event.target.classList.contains('image-zoom-overlay')) {
@@ -361,7 +243,7 @@ function handleMouseUp() {
   isDragging.value = false
 }
 
-// 监听键盘事件
+// 监听键盘事件（使用生命周期钩子管理，避免泄漏）
 function handleKeyDown(event) {
   if (!props.visible) return
   switch (event.key) {
@@ -387,9 +269,13 @@ function handleKeyDown(event) {
   }
 }
 
-if (typeof window !== 'undefined') {
+onMounted(() => {
   window.addEventListener('keydown', handleKeyDown)
-}
+})
+
+onBeforeUnmount(() => {
+  window.removeEventListener('keydown', handleKeyDown)
+})
 </script>
 
 <style scoped>

package/src/components/MermaidNodeView.vue

@@ -44,6 +44,7 @@
 import { ref, computed, watch, onMounted, nextTick } from 'vue'
 import { nodeViewProps, NodeViewWrapper } from '@tiptap/vue-3'
 import mermaid from 'mermaid'
+import { getMermaidCache, setMermaidCache } from '../composables/useMermaidCache.js'
 
 const props = defineProps(nodeViewProps)
 
@@ -63,17 +64,24 @@ async function renderChart() {
     renderError.value = false
     return
   }
+  // 优先使用缓存
+  const cached = getMermaidCache(text)
+  if (cached) {
+    svgContent.value = cached
+    renderError.value = false
+    return
+  }
   try {
     const id = 'mermaid-editor-' + Math.random().toString(36).substr(2, 9)
     const { svg } = await mermaid.render(id, text)
     svgContent.value = svg
     renderError.value = false
+    // 写入缓存
+    setMermaidCache(text, svg)
   } catch (e) {
     console.error('Mermaid 编辑器渲染失败:', e)
     svgContent.value = ''
     renderError.value = true
-    // 清理 Mermaid 渲染失败时残留的 DOM 元素
-    const errId = 'mermaid-editor-' // 前缀匹配清理
     document.querySelectorAll('[id^="mermaid-editor-"][id$="-svg"]').forEach(el => {
       if (el.closest('.mermaid-block-wrapper') === null) el.remove()
     })

package/src/components/MobileSearch.vue

@@ -0,0 +1,97 @@
+<template>
+  <div class="mobile-search-page">
+    <!-- 搜索输入区 -->
+    <div class="mobile-search-header">
+      <div class="mobile-search-input-wrapper">
+        <Search :size="16" class="mobile-search-icon" />
+        <input
+          ref="inputRef"
+          type="text"
+          class="mobile-search-input"
+          placeholder="搜索文档..."
+          v-model="searchQuery"
+          @input="doSearch(searchQuery)"
+          @keydown.escape="$emit('close')"
+          @keydown.enter="handleEnter"
+          @keydown.up.prevent="moveSelection(-1)"
+          @keydown.down.prevent="moveSelection(1)"
+        />
+        <button v-if="searchQuery" class="mobile-search-clear" @click="clearSearch">
+          <X :size="14" />
+        </button>
+      </div>
+      <button class="mobile-search-cancel" @click="$emit('close')">取消</button>
+    </div>
+    <!-- 搜索结果 -->
+    <div class="mobile-search-results">
+      <div v-if="!searchReady && indexBuilding" class="mobile-search-tip">
+        正在构建索引...
+      </div>
+      <div v-else-if="searchQuery && searchResults.length === 0" class="mobile-search-empty">
+        没有找到相关文档
+      </div>
+      <template v-else-if="searchResults.length > 0">
+        <div
+          v-for="(item, index) in searchResults"
+          :key="item.key"
+          :class="['mobile-search-item', { active: index === selectedIndex }]"
+          @click="selectResult(item)"
+        >
+          <FileText :size="14" class="mobile-search-item-icon" />
+          <span class="mobile-search-item-title">{{ item.title }}</span>
+        </div>
+      </template>
+      <div v-else class="mobile-search-tip">输入关键词搜索文档内容</div>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { ref, watch, nextTick, onMounted } from 'vue'
+import { Search, X, FileText } from 'lucide-vue-next'
+import { useSearch } from '../composables/useSearch.js'
+
+const emit = defineEmits(['close', 'select'])
+
+const { searchQuery, searchResults, searchReady, indexBuilding, doSearch, openSearch } = useSearch()
+
+const inputRef = ref(null)
+const selectedIndex = ref(0)
+
+// 页面挂载时自动聚焦并构建索引
+onMounted(async () => {
+  await openSearch()
+  await nextTick()
+  inputRef.value?.focus()
+})
+
+// 搜索结果变化时重置选中
+watch(searchResults, () => {
+  selectedIndex.value = 0
+})
+
+function clearSearch() {
+  searchQuery.value = ''
+  searchResults.value = []
+  inputRef.value?.focus()
+}
+
+function moveSelection(delta) {
+  const len = searchResults.value.length
+  if (len === 0) return
+  selectedIndex.value = (selectedIndex.value + delta + len) % len
+}
+
+function handleEnter() {
+  if (searchResults.value.length > 0) {
+    selectResult(searchResults.value[selectedIndex.value])
+  }
+}
+
+function selectResult(item) {
+  // 清理搜索状态
+  searchQuery.value = ''
+  searchResults.value = []
+  emit('select', item.key)
+}
+</script>

package/src/components/TableOfContents.vue

@@ -18,6 +18,10 @@
       </div>
     </div>
     <nav ref="tocNavRef" class="toc-nav">
+      <!-- 左侧连续竖线 -->
+      <div class="toc-track"></div>
+      <!-- marker 滑块（平滑过渡） -->
+      <div class="toc-marker" :style="markerStyle"></div>
       <template v-for="(item, index) in tocItems" :key="item.id">
         <!-- 顶级标题（h1/h2）：可点击折叠 -->
         <a
@@ -53,7 +57,7 @@
 </template>
 
 <script setup>
-import { ref, watch, nextTick } from 'vue'
+import { ref, watch, nextTick, reactive } from 'vue'
 import { List, ChevronRight, ChevronsDownUp, ChevronsUpDown } from 'lucide-vue-next'
 
 const props = defineProps({
@@ -68,6 +72,9 @@ defineEmits(['scroll-to', 'toggle'])
 // 目录导航容器 ref
 const tocNavRef = ref(null)
 
+// marker 滑块位置
+const markerStyle = reactive({ top: '0px', height: '0px', opacity: 0 })
+
 // 记录被收起的顶级标题 id
 const collapsedSections = ref(new Set())
 
@@ -125,9 +132,30 @@ function collapseAll() {
   collapsedSections.value = ids
 }
 
+// 更新 marker 滑块位置
+function updateMarker() {
+  if (!props.activeHeading || !tocNavRef.value) {
+    markerStyle.opacity = 0
+    return
+  }
+  const el = tocNavRef.value.querySelector(`[data-toc-id="${props.activeHeading}"]`)
+  if (!el) {
+    markerStyle.opacity = 0
+    return
+  }
+  const navRect = tocNavRef.value.getBoundingClientRect()
+  const elRect = el.getBoundingClientRect()
+  markerStyle.top = `${elRect.top - navRect.top + tocNavRef.value.scrollTop}px`
+  markerStyle.height = `${elRect.height}px`
+  markerStyle.opacity = 1
+}
+
 // 滚动时自动展开当前激活标题所在的折叠分组，并将目录项滚动到可视区域
 watch(() => props.activeHeading, (id) => {
-  if (!id) return
+  if (!id) {
+    markerStyle.opacity = 0
+    return
+  }
   const index = props.tocItems.findIndex(item => item.id === id)
   if (index === -1) return
   // 如果激活的是子标题，找到其父级并展开
@@ -139,17 +167,25 @@ watch(() => props.activeHeading, (id) => {
       collapsedSections.value = next
     }
   }
-  // 等 DOM 更新后，将激活项滚动到目录可视区域
+  // 等 DOM 更新后，将激活项滚动到目录可视区域，并更新 marker
   nextTick(() => {
     const el = tocNavRef.value?.querySelector(`[data-toc-id="${id}"]`)
-    if (el) {
-      el.scrollIntoView({ block: 'center', behavior: 'smooth' })
+    if (el && tocNavRef.value) {
+      // 只在 TOC 导航容器内滚动，避免 scrollIntoView 冒泡影响主内容区导致抖动
+      const navRect = tocNavRef.value.getBoundingClientRect()
+      const elRect = el.getBoundingClientRect()
+      const elCenter = elRect.top + elRect.height / 2
+      const navCenter = navRect.top + navRect.height / 2
+      const offset = elCenter - navCenter
+      tocNavRef.value.scrollBy({ top: offset, behavior: 'smooth' })
     }
+    updateMarker()
   })
 })
 
-// 文档切换时重置折叠状态
+// 文档切换时重置折叠状态和 marker
 watch(() => props.tocItems, () => {
   collapsedSections.value = new Set()
+  markerStyle.opacity = 0
 })
 </script>

package/src/composables/useDocManager.js

@@ -4,8 +4,9 @@ import { useMarkdown } from './useMarkdown.js'
 import { useSearch } from './useSearch.js'
 import { useScroll } from './useScroll.js'
 import { useMobile } from './useMobile.js'
-import { findDoc, findFirstDoc, findReadmeDoc, findDocByHash, expandParents, flattenDocsList, expandAll, collapseAll } from './useDocTree.js'
+import { findDoc, findFirstDoc, findReadmeDoc, findDocByHash, expandParents, flattenDocsList, expandAll, collapseAll, buildHashIndex } from './useDocTree.js'
 import { stripOrderPrefix } from './useDocHash.js'
+import { clearMermaidCache } from './useMermaidCache.js'
 
 // 等待内容区域图片加载完成
 async function waitForContentImages(timeoutMs = 3000) {
@@ -39,7 +40,11 @@ export function useDocManager() {
     handleScroll: _handleScroll,
     scrollToHeading: _scrollToHeading,
     scrollToTop,
-    setTocItems
+    setTocItems,
+    rebuildHeadingsCache,
+    clearActiveHeading,
+    isSuppressHashClear,
+    lockHeading
   } = useScroll()
   const { isMobile, mobileDrawerOpen } = useMobile()
 
@@ -55,31 +60,52 @@ export function useDocManager() {
     return { scrollTop: scrollTop ?? getScrollTop() }
   }
 
+  // URL 锚点同步：统一由 watch 驱动，scrollToHeading 不再直接操作 URL
+  // _pendingPush: 标记下一次 activeHeading 变化是否需要 pushState（点击目录项）
+  let _pendingPush = false
+  let _hashUpdateTimer = null
+
+  watch(activeHeading, (id, oldId) => {
+    if (!currentDoc.value) return
+
+    // 文档切换导致的清空，不动 URL
+    if (!id && isSuppressHashClear()) return
+
+    // 取出并重置 push 标记
+    const shouldPush = _pendingPush
+    _pendingPush = false
+
+    if (_hashUpdateTimer) clearTimeout(_hashUpdateTimer)
+    _hashUpdateTimer = setTimeout(() => {
+      _hashUpdateTimer = null
+      const base = `/${docHash(currentDoc.value)}`
+      const url = id ? `${base}#${id}` : base
+      const current = window.location.pathname + window.location.hash
+      if (current === url) return
+
+      if (shouldPush) {
+        // 先保存当前滚动位置到旧条目
+        history.replaceState(makeState(), '', current)
+        history.pushState(makeState(), '', url)
+      } else {
+        history.replaceState(makeState(), '', url)
+      }
+    }, 100)
+  })
+
   function handleScroll(e) {
     _handleScroll(e)
-    if (activeHeading.value && currentDoc.value) {
-      history.replaceState(makeState(), '', `/${docHash(currentDoc.value)}#${activeHeading.value}`)
-    }
   }
 
   function scrollToHeading(id, { push = false } = {}) {
-    if (push && currentDoc.value) {
-      history.replaceState(makeState(), '', window.location.href)
-    }
+    if (push) _pendingPush = true
     _scrollToHeading(id)
-    if (currentDoc.value) {
-      const url = `/${docHash(currentDoc.value)}#${id}`
-      if (push) {
-        history.pushState(makeState(), '', url)
-      } else {
-        history.replaceState(makeState(), '', url)
-      }
-    }
   }
 
   // ===== 文档列表加载 =====
   async function loadDocsList() {
     docsList.value = await docService.fetchDocsList()
+    buildHashIndex(docsList.value, docHash)
     restoreExpandedState()
     buildIndex(docsList.value)
   }
@@ -105,6 +131,7 @@ export function useDocManager() {
     currentDoc.value = key
     showWelcome.value = false
     lastContentHash = ''
+    clearMermaidCache()
     docService.resetContentEtag()
     const hash = docHash(key)
     const url = anchor ? `/${hash}#${anchor}` : `/${hash}`
@@ -131,6 +158,18 @@ export function useDocManager() {
         } else {
           await renderMarkdown(content, key, docsList.value)
         }
+        // 渲染完成后重建标题缓存（编辑模式需等 tiptap 渲染完成）
+        await nextTick()
+        rebuildHeadingsCache()
+        // 切换文档时清空 activeHeading（标记为文档切换，不清 URL hash）
+        // 同时取消 pending 的 hash 同步 timer
+        if (_hashUpdateTimer) { clearTimeout(_hashUpdateTimer); _hashUpdateTimer = null }
+        // 如果有锚点参数，先锁定再清空，防止 scrollTop=0 触发的滚动检测覆盖锚点
+        if (anchor) {
+          lockHeading(anchor)
+        } else {
+          clearActiveHeading()
+        }
         const contentEl = document.querySelector('.content')
         if (contentEl) contentEl.scrollTop = 0
         // 动态更新页面标题（SEO + 浏览器标签页）
@@ -189,10 +228,68 @@ export function useDocManager() {
   }
 
   // ===== 内容区点击处理 =====
+
+  // 复制锚点链接到剪贴板（通过 class 切换锚点旁提示文字）
+  async function copyAnchorLink(anchorId, anchorEl) {
+    const base = currentDoc.value ? `/${docHash(currentDoc.value)}` : window.location.pathname
+    const url = `${window.location.origin}${base}#${anchorId}`
+    try {
+      await navigator.clipboard.writeText(url)
+      anchorEl.classList.add('anchor-copied')
+      setTimeout(() => anchorEl.classList.remove('anchor-copied'), 1500)
+    } catch {
+      anchorEl.classList.add('anchor-copy-error')
+      setTimeout(() => anchorEl.classList.remove('anchor-copy-error'), 1500)
+    }
+  }
+
   function handleContentClick(event, { onZoom }) {
     const target = event.target
+
+    // 优先判断图片放大（即使图片在链接内，也走放大逻辑而非链接跳转）
+    const isImg = target.tagName === 'IMG' && target.classList.contains('zoomable-image')
+    const mermaidEl = target.closest('.mermaid') || target.closest('.mermaid-svg')
+    const isMermaid = mermaidEl && mermaidEl.classList.contains('zoomable-image')
+    if (isImg || isMermaid) {
+      event.preventDefault()
+      const container = document.querySelector('.markdown-content')
+      if (!container) return
+      const allZoomable = [...container.querySelectorAll('.zoomable-image')]
+      const images = allZoomable.map(el => {
+        if (el.tagName === 'IMG') {
+          return `<img src="${el.src}" alt="${el.alt || ''}" style="max-width: 100%; height: auto;" />`
+        }
+        const clone = el.cloneNode(true)
+        clone.querySelectorAll('.mermaid-copy-btn, .image-copy-btn').forEach(btn => btn.remove())
+        return clone.innerHTML
+      })
+      const clickedEl = isImg ? target : mermaidEl
+      const index = allZoomable.indexOf(clickedEl)
+      onZoom({ images, index: Math.max(index, 0) })
+      return
+    }
+
+    // 链接处理
     const link = target.closest('a')
     if (link) {
+      // 标题锚点点击：复制链接 + 跳转 + 高亮
+      if (link.classList.contains('heading-anchor')) {
+        event.preventDefault()
+        const anchorId = link.dataset.anchor
+        if (anchorId) {
+          copyAnchorLink(anchorId, link)
+          scrollToHeading(anchorId, { push: true })
+          // 触发高亮闪烁动画
+          const heading = document.getElementById(anchorId)
+          if (heading) {
+            heading.classList.remove('heading-flash')
+            void heading.offsetWidth // 强制 reflow 重置动画
+            heading.classList.add('heading-flash')
+            heading.addEventListener('animationend', () => heading.classList.remove('heading-flash'), { once: true })
+          }
+        }
+        return
+      }
       const docKey = link.dataset.docKey
       if (docKey) {
         event.preventDefault()
@@ -211,25 +308,6 @@ export function useDocManager() {
       }
       return
     }
-    const isImg = target.tagName === 'IMG' && target.classList.contains('zoomable-image')
-    const mermaidEl = target.closest('.mermaid') || target.closest('.mermaid-svg')
-    const isMermaid = mermaidEl && mermaidEl.classList.contains('zoomable-image')
-    if (isImg || isMermaid) {
-      const container = document.querySelector('.markdown-content')
-      if (!container) return
-      const allZoomable = [...container.querySelectorAll('.zoomable-image')]
-      const images = allZoomable.map(el => {
-        if (el.tagName === 'IMG') {
-          return `<img src="${el.src}" alt="${el.alt || ''}" style="max-width: 100%; height: auto;" />`
-        }
-        const clone = el.cloneNode(true)
-        clone.querySelectorAll('.mermaid-copy-btn, .image-copy-btn').forEach(btn => btn.remove())
-        return clone.innerHTML
-      })
-      const clickedEl = isImg ? target : mermaidEl
-      const index = allZoomable.indexOf(clickedEl)
-      onZoom({ images, index: Math.max(index, 0) })
-    }
   }
 
   // ===== 计算属性 =====
@@ -239,18 +317,19 @@ export function useDocManager() {
     return doc?.label || '文档'
   })
 
+  // 扁平化文档列表（缓存，供 prevDoc / nextDoc 共享）
+  const flatList = computed(() => flattenDocsList(docsList.value))
+
   const prevDoc = computed(() => {
     if (!currentDoc.value) return null
-    const flat = flattenDocsList(docsList.value)
-    const idx = flat.findIndex(d => d.key === currentDoc.value)
-    return idx > 0 ? flat[idx - 1] : null
+    const idx = flatList.value.findIndex(d => d.key === currentDoc.value)
+    return idx > 0 ? flatList.value[idx - 1] : null
   })
 
   const nextDoc = computed(() => {
     if (!currentDoc.value) return null
-    const flat = flattenDocsList(docsList.value)
-    const idx = flat.findIndex(d => d.key === currentDoc.value)
-    return idx >= 0 && idx < flat.length - 1 ? flat[idx + 1] : null
+    const idx = flatList.value.findIndex(d => d.key === currentDoc.value)
+    return idx >= 0 && idx < flatList.value.length - 1 ? flatList.value[idx + 1] : null
   })
 
   function handleSearchSelect(key) {
@@ -268,9 +347,13 @@ export function useDocManager() {
   watch(editMode, async (newVal, oldVal) => {
     if (oldVal && !newVal && rawMarkdown.value && currentDoc.value) {
       await renderMarkdown(rawMarkdown.value, currentDoc.value, docsList.value)
+      await nextTick()
+      rebuildHeadingsCache()
     }
     if (newVal && rawMarkdown.value) {
       extractTOCFromMarkdown(rawMarkdown.value, tocItems)
+      await nextTick()
+      rebuildHeadingsCache()
     }
   })
 
@@ -328,6 +411,7 @@ export function useDocManager() {
     // 保存展开状态 → 替换 → 恢复
     const expandedKeys = getExpandedKeys(docsList.value)
     docsList.value = newTree
+    buildHashIndex(docsList.value, docHash)
     applyExpandedState(docsList.value, expandedKeys)
     if (currentDoc.value) expandParents(docsList.value, currentDoc.value)
     buildIndex(docsList.value)
@@ -346,10 +430,11 @@ export function useDocManager() {
     const hashStr = String(hash)
     if (hashStr === lastContentHash) return
     lastContentHash = hashStr
-    rawMarkdown.value = content
-    // 编辑模式下只更新 rawMarkdown（编辑器组件会自行比对内容决定是否刷新）
+    // 编辑模式下编辑器是内容权威来源，不回写 rawMarkdown 避免循环抖动
     if (editMode.value) return
+    rawMarkdown.value = content
     await renderMarkdown(content, currentDoc.value, docsList.value)
+    rebuildHeadingsCache()
   }
 
   // ===== 写操作 =====
@@ -403,6 +488,7 @@ export function useDocManager() {
         const contentEl = document.querySelector('.content')
         if (contentEl) contentEl.scrollTo({ top: savedScroll, behavior: 'smooth' })
       } else if (anchor) {
+        // popstate 同文档锚点跳转，_scrollToHeading 内部有锁
         _scrollToHeading(decodeURIComponent(anchor))
       } else {
         const contentEl = document.querySelector('.content')
@@ -415,10 +501,14 @@ export function useDocManager() {
     await loadDoc(doc.key, { replace: true, keepState: savedScroll != null, anchor: anchor ? decodeURIComponent(anchor) : '' })
     if (savedScroll != null) {
       await nextTick()
+      await waitForContentImages()
       const contentEl = document.querySelector('.content')
       if (contentEl) contentEl.scrollTo({ top: savedScroll })
     } else if (anchor) {
-      await nextTick(); await waitForContentImages(); _scrollToHeading(decodeURIComponent(anchor))
+      const decodedAnchor = decodeURIComponent(anchor)
+      await nextTick(); await waitForContentImages()
+      // 复用 scrollToHeading，编辑模式下通过 _syncHeadingIds 注入的 id 或文本匹配均可定位
+      _scrollToHeading(decodedAnchor)
     }
   }