diff --git a/package.json b/package.json
index 5d38afac7..ec203754c 100644
--- a/package.json
+++ b/package.json
@@ -21,8 +21,11 @@
     "@dhlx/vitepress-plugin-drawio": "^0.0.10",
     "@panzoom/panzoom": "^4.6.2",
     "@types/node": "^25.6.2",
+    "@vueuse/core": "^12.4.0",
+    "@vueuse/integrations": "^12.4.0",
     "gray-matter": "4.0.3",
     "linkedom": "0.18.13",
+    "mark.js": "8.11.1",
     "markdown-it-mathjax3": "^4.3.2",
     "mermaid": "^10.9.6",
     "pagedjs": "0.4.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e9fc9056d..0cbf5b2b7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -21,12 +21,21 @@ importers:
       '@types/node':
         specifier: ^25.6.2
         version: 25.6.2
+      '@vueuse/core':
+        specifier: ^12.4.0
+        version: 12.8.2
+      '@vueuse/integrations':
+        specifier: ^12.4.0
+        version: 12.8.2(focus-trap@7.8.0)
       gray-matter:
         specifier: 4.0.3
         version: 4.0.3
       linkedom:
         specifier: 0.18.13
         version: 0.18.13
+      mark.js:
+        specifier: 8.11.1
+        version: 8.11.1
       markdown-it-mathjax3:
         specifier: ^4.3.2
         version: 4.3.2
@@ -817,6 +826,7 @@ packages:
   '@xmldom/xmldom@0.9.10':
     resolution: {integrity: sha512-A9gOqLdi6cV4ibazAjcQufGj0B1y/vDqYrcuP6d/6x8P27gRS8643Dj9o1dEKtB6O7fwxb2FgBmJS2mX7gpvdw==}
     engines: {node: '>=14.6'}
+    deprecated: this version has critical issues, please update to the latest version
 
   algoliasearch@5.52.1:
     resolution: {integrity: sha512-fHA8+kXTbjagw3jkLiaS7KKrH8qe2DyOsiUhGlN4cdT77PEsfqXZl7ewDk1hsg+pJnPlnE50XtLxjR91iJOpmg==}
diff --git a/site/.vitepress/config/index.ts b/site/.vitepress/config/index.ts
index a1f17d0cc..42dc5cde9 100644
--- a/site/.vitepress/config/index.ts
+++ b/site/.vitepress/config/index.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
 import withDrawio from '@dhlx/vitepress-plugin-drawio'
 import { navEn } from './nav'
 import { buildSidebar } from './sidebar'
-import { sharedThemeConfig, sharedMarkdown, makeSocialLinks } from './shared'
+import { sharedThemeConfig, sharedMarkdown, makeSocialLinks, localSearchBoxAlias } from './shared'
 import { createReadStream, existsSync } from 'node:fs'
 import { join, normalize } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -35,6 +35,9 @@ function serveCodeExamplesInDev() {
 export default withDrawio(defineConfig({
   vite: {
     plugins: [serveCodeExamplesInDev()],
+    resolve: {
+      alias: localSearchBoxAlias,
+    },
     ssr: {
       // mermaid / @panzoom/panzoom 都只在客户端 onMounted 后动态 import 求值,
       // SSR 阶段不能也不应打包求值(mermaid 访问 document、panzoom 访问 DOM)。
diff --git a/site/.vitepress/config/shared.ts b/site/.vitepress/config/shared.ts
index 9345c678f..d63c50601 100644
--- a/site/.vitepress/config/shared.ts
+++ b/site/.vitepress/config/shared.ts
@@ -38,6 +38,16 @@ export const sharedMarkdown = {
   },
 }
 
+// 覆盖 vitepress 内置搜索盒:VPLocalSearchBox 只被 VPNavBarSearch 以
+// './VPLocalSearchBox.vue' 这一 specifier 引用,alias 指到我们的覆盖版
+// (索引构建+查询挪进 Web Worker,修 issue #156 的搜索卡顿)。
+// index.ts(dev/单体 build)与 sharedBase(分卷构建)都要用,单一来源防漏改。
+export const localSearchBoxAlias = {
+  './VPLocalSearchBox.vue': fileURLToPath(
+    new URL('../theme/components/VPLocalSearchBox.vue', import.meta.url)
+  ),
+}
+
 export const sharedBase = {
   base: '/Tutorial_AwesomeModernCPP/',
   cleanUrls: true,
@@ -54,6 +64,9 @@ export const sharedBase = {
   },
 
   vite: {
+    resolve: {
+      alias: localSearchBoxAlias,
+    },
     build: {
       chunkSizeWarningLimit: 5000,
     },
diff --git a/site/.vitepress/theme/components/VPLocalSearchBox.vue b/site/.vitepress/theme/components/VPLocalSearchBox.vue
new file mode 100644
index 000000000..8b17525ce
--- /dev/null
+++ b/site/.vitepress/theme/components/VPLocalSearchBox.vue
@@ -0,0 +1,974 @@
+<script lang="ts">
+// 摘要缓存放模块级(而非组件实例级):搜索盒开关不丢已提取的摘要,
+// 重开详细视图不用重新离屏 mount 一轮页面组件。locale 切换时在
+// 下面的索引加载 watch 里整体清空。
+const excerptCache = new LRUCache<string, Map<string, string>>(16) // 16 files
+</script>
+
+<script lang="ts" setup>
+// 覆盖 vitepress 内置 VPLocalSearchBox(via shared.ts 的 vite alias),修
+// issue #156:全站搜索索引是一块 13MB 级 JSON,原版把 JSON.parse、
+// MiniSearch 重建和每次击键的查询全放在主线程,搜索一开页面就冻住。
+// 这里只改搜索后端:索引构建 + 查询走 Web Worker(见 local-search-backend.ts);
+// 详细视图的摘要提取依赖离屏 mount 页面组件、进不了 worker,改为逐页处理
+// + 页间让出主线程 + 渐进填充,期间列表底部给出「正在生成摘要…」提示。
+// 其余(键盘导航/高亮/样式)与上游 1.6.4 保持一致,方便日后对 diff。
+import localSearchIndex from '@localSearchIndex'
+import {
+  computedAsync,
+  debouncedWatch,
+  onKeyStroke,
+  useEventListener,
+  useLocalStorage,
+  useScrollLock,
+  useSessionStorage
+} from '@vueuse/core'
+import { useFocusTrap } from '@vueuse/integrations/useFocusTrap'
+import Mark from 'mark.js/src/vanilla.js'
+import type { SearchResult } from 'minisearch'
+import { dataSymbol, inBrowser, useData, useRouter } from 'vitepress'
+import { pathToFile } from 'vitepress/dist/client/app/utils.js'
+import { escapeRegExp } from 'vitepress/dist/client/shared.js'
+import { LRUCache } from 'vitepress/dist/client/theme-default/support/lru.js'
+import { createSearchTranslate } from 'vitepress/dist/client/theme-default/support/translation.js'
+import {
+  computed,
+  createApp,
+  markRaw,
+  nextTick,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  shallowRef,
+  watch,
+  watchEffect,
+  type Ref
+} from 'vue'
+import { getSearchBackend } from '../local-search-backend'
+
+const emit = defineEmits<{
+  (e: 'close'): void
+}>()
+
+const el = shallowRef<HTMLElement>()
+const resultsEl = shallowRef<HTMLElement>()
+
+/* Search */
+
+const searchIndexData = shallowRef(localSearchIndex)
+
+// hmr
+if (import.meta.hot) {
+  import.meta.hot.accept('/@localSearchIndex', (m) => {
+    if (m) {
+      searchIndexData.value = m.default
+    }
+  })
+}
+
+interface Result {
+  title: string
+  titles: string[]
+  text?: string
+}
+
+const vitePressData = useData()
+const { activate } = useFocusTrap(el, {
+  immediate: true,
+  allowOutsideClick: true,
+  clickOutsideDeactivates: true,
+  escapeDeactivates: true
+})
+const { localeIndex, theme } = vitePressData
+
+/* 搜索后端:worker 优先,失败回退主线程(原行为) */
+const backend = getSearchBackend()
+
+const indexReady = ref(false)
+const loadingIndex = ref(false)
+let loadToken = 0
+
+// 详细视图摘要生成中(列表底部提示用);fillingExcerpts 标记渐进填充,
+// 期间不重置用户的选择
+const excerptLoading = ref(false)
+let fillingExcerpts = false
+
+// 让出主线程:优先用 scheduler.yield(事件优先级保真),老浏览器退 setTimeout
+function yieldToMain(): Promise<void> {
+  const sched = (
+    globalThis as unknown as { scheduler?: { yield?: () => Promise<void> } }
+  ).scheduler
+  return sched?.yield ? sched.yield() : new Promise((r) => setTimeout(r, 0))
+}
+
+function getMiniSearchOptions() {
+  return {
+    fields: ['title', 'titles', 'text'],
+    storeFields: ['title', 'titles'],
+    searchOptions: {
+      fuzzy: 0.2,
+      prefix: true,
+      boost: { title: 4, text: 2, titles: 1 },
+      ...(theme.value.search?.provider === 'local' &&
+        theme.value.search.options?.miniSearch?.searchOptions)
+    },
+    ...(theme.value.search?.provider === 'local' &&
+      theme.value.search.options?.miniSearch?.options)
+  }
+}
+
+const disableQueryPersistence = computed(() => {
+  return (
+    theme.value.search?.provider === 'local' &&
+    theme.value.search.options?.disableQueryPersistence === true
+  )
+})
+
+const filterText = disableQueryPersistence.value
+  ? ref('')
+  : useSessionStorage('vitepress:local-search-filter', '')
+
+const showDetailedList = useLocalStorage(
+  'vitepress:local-search-detailed-list',
+  theme.value.search?.provider === 'local' &&
+    theme.value.search.options?.detailedView === true
+)
+
+const disableDetailedView = computed(() => {
+  return (
+    theme.value.search?.provider === 'local' &&
+    (theme.value.search.options?.disableDetailedView === true ||
+      theme.value.search.options?.detailedView === false)
+  )
+})
+
+const buttonText = computed(() => {
+  const options = theme.value.search?.options ?? theme.value.algolia
+
+  return (
+    options?.locales?.[localeIndex.value]?.translations?.button?.buttonText ||
+    options?.translations?.button?.buttonText ||
+    'Search'
+  )
+})
+
+watchEffect(() => {
+  if (disableDetailedView.value) {
+    showDetailedList.value = false
+  }
+})
+
+const results: Ref<(SearchResult & Result)[]> = shallowRef([])
+
+const enableNoResults = ref(false)
+
+watch(filterText, () => {
+  enableNoResults.value = false
+})
+
+const mark = computedAsync(async () => {
+  if (!resultsEl.value) return
+  return markRaw(new Mark(resultsEl.value))
+}, null)
+
+const cache = excerptCache
+
+// 索引加载:locale 切换 / dev hmr 时重建。token 防乱序——旧一轮的完成
+// 事件不允许覆盖新一轮的状态。
+watch(
+  () => [searchIndexData.value, localeIndex.value] as const,
+  async () => {
+    const token = ++loadToken
+    loadingIndex.value = true
+    indexReady.value = false
+    // 索引换了,页面摘要缓存一并作废
+    cache.clear()
+    try {
+      const json = (await searchIndexData.value[localeIndex.value]?.())?.default
+      if (!json || token !== loadToken) return
+      await backend.init(json, getMiniSearchOptions())
+      if (token !== loadToken) return
+      indexReady.value = true
+    } catch (err) {
+      console.error(err)
+    } finally {
+      if (token === loadToken) loadingIndex.value = false
+    }
+  },
+  { immediate: true }
+)
+
+debouncedWatch(
+  () => [filterText.value, showDetailedList.value, indexReady.value] as const,
+  async ([filterTextValue, showDetailedListValue, ready], _old, onCleanup) => {
+    let canceled = false
+    onCleanup(() => {
+      canceled = true
+    })
+
+    if (!ready) return
+
+    // Search(查询在 worker/回退后端里跑;旧查询的迟到结果被 canceled 丢弃)
+    const found = await backend.search(filterTextValue)
+    if (canceled) return
+    results.value = found as (SearchResult & Result)[]
+    enableNoResults.value = true
+
+    // Highlighting
+    // 摘要提取要离屏 mount 页面组件(进不了 worker),单页动辄上百毫秒;
+    // 原版一次跑完 16 页,详细视图一开整段冻结。改为逐页处理 + 页间让出
+    // 主线程,每页完成即渐进填充该条结果的摘要(issue #156)。
+    if (showDetailedListValue && results.value.length) {
+      excerptLoading.value = true
+      fillingExcerpts = true
+      try {
+        const mods = await Promise.all(
+          results.value.map((r) => fetchExcerpt(r.id))
+        )
+        if (canceled) return
+
+        for (const { id, mod } of mods) {
+          const mapId = id.slice(0, id.indexOf('#'))
+          let map = cache.get(mapId)
+          if (!map) {
+            map = new Map()
+            cache.set(mapId, map)
+            const comp = mod.default ?? mod
+            if (comp?.render || comp?.setup) {
+              const app = createApp(comp)
+              // Silence warnings about missing components
+              app.config.warnHandler = () => {}
+              app.provide(dataSymbol, vitePressData)
+              Object.defineProperties(app.config.globalProperties, {
+                $frontmatter: {
+                  get() {
+                    return vitePressData.frontmatter.value
+                  }
+                },
+                $params: {
+                  get() {
+                    return vitePressData.page.value.params
+                  }
+                }
+              })
+              const div = document.createElement('div')
+              app.mount(div)
+              const headings = div.querySelectorAll('h1, h2, h3, h4, h5, h6')
+              headings.forEach((el) => {
+                const href = el.querySelector('a')?.getAttribute('href')
+                const anchor = href?.startsWith('#') && href?.slice(1)
+                if (!anchor) return
+                let html = ''
+                while ((el = el.nextElementSibling!) && !/^h[1-6]$/i.test(el.tagName))
+                  html += el.outerHTML
+                map!.set(anchor, html)
+              })
+              app.unmount()
+            }
+          }
+
+          // 这条结果的摘要先上屏,列表渐进长出内容
+          const [, anchor] = id.split('#')
+          const text = map.get(anchor) ?? ''
+          const at = results.value.findIndex((r) => r.id === id)
+          if (at > -1) {
+            results.value = results.value.map((r, i) =>
+              i === at ? { ...r, text } : r
+            )
+          }
+
+          await yieldToMain()
+          if (canceled) return
+        }
+      } finally {
+        fillingExcerpts = false
+        excerptLoading.value = false
+      }
+    }
+
+    const terms = new Set<string>()
+    for (const r of results.value) {
+      for (const term in r.match) {
+        terms.add(term)
+      }
+    }
+
+    await nextTick()
+    if (canceled) return
+
+    await new Promise((r) => {
+      mark.value?.unmark({
+        done: () => {
+          mark.value?.markRegExp(formMarkRegex(terms), { done: r })
+        }
+      })
+    })
+
+    const excerpts = el.value?.querySelectorAll('.result .excerpt') ?? []
+    for (const excerpt of excerpts) {
+      excerpt
+        .querySelector('mark[data-markjs="true"]')
+        ?.scrollIntoView({ block: 'center' })
+    }
+    // FIXME: without this whole page scrolls to the bottom
+    resultsEl.value?.firstElementChild?.scrollIntoView({ block: 'start' })
+  },
+  { debounce: 200, immediate: true }
+)
+
+async function fetchExcerpt(id: string) {
+  const file = pathToFile(id.slice(0, id.indexOf('#')))
+  try {
+    if (!file) throw new Error(`Cannot find file for id: ${id}`)
+    return { id, mod: await import(/*@vite-ignore*/ file) }
+  } catch (e) {
+    console.error(e)
+    return { id, mod: {} }
+  }
+}
+
+/* Search input focus */
+
+const searchInput = ref<HTMLInputElement>()
+const disableReset = computed(() => {
+  return filterText.value?.length <= 0
+})
+function focusSearchInput(select = true) {
+  searchInput.value?.focus()
+  select && searchInput.value?.select()
+}
+
+onMounted(() => {
+  focusSearchInput()
+})
+
+function onSearchBarClick(event: PointerEvent) {
+  if (event.pointerType === 'mouse') {
+    focusSearchInput()
+  }
+}
+
+/* Search keyboard selection */
+
+const selectedIndex = ref(-1)
+const disableMouseOver = ref(true)
+
+watch(results, (r) => {
+  // 摘要渐进填充期间不重置,保住用户正在浏览的选择
+  if (fillingExcerpts) return
+  selectedIndex.value = r.length ? 0 : -1
+  scrollToSelectedResult()
+})
+
+function scrollToSelectedResult() {
+  nextTick(() => {
+    const selectedEl = document.querySelector('.result.selected')
+    selectedEl?.scrollIntoView({ block: 'nearest' })
+  })
+}
+
+onKeyStroke('ArrowUp', (event) => {
+  event.preventDefault()
+  selectedIndex.value--
+  if (selectedIndex.value < 0) {
+    selectedIndex.value = results.value.length - 1
+  }
+  disableMouseOver.value = true
+  scrollToSelectedResult()
+})
+
+onKeyStroke('ArrowDown', (event) => {
+  event.preventDefault()
+  selectedIndex.value++
+  if (selectedIndex.value >= results.value.length) {
+    selectedIndex.value = 0
+  }
+  disableMouseOver.value = true
+  scrollToSelectedResult()
+})
+
+const router = useRouter()
+
+onKeyStroke('Enter', (e) => {
+  if (e.isComposing) return
+
+  if (e.target instanceof HTMLButtonElement && e.target.type !== 'submit')
+    return
+
+  const selectedPackage = results.value[selectedIndex.value]
+  if (e.target instanceof HTMLInputElement && !selectedPackage) {
+    e.preventDefault()
+    return
+  }
+
+  if (selectedPackage) {
+    router.go(selectedPackage.id)
+    emit('close')
+  }
+})
+
+onKeyStroke('Escape', () => {
+  emit('close')
+})
+
+// Translations
+interface ModalTranslations {
+  displayDetails?: string
+  resetButtonTitle?: string
+  backButtonTitle?: string
+  noResultsText?: string
+  footer?: {
+    selectText?: string
+    selectKeyAriaLabel?: string
+    navigateText?: string
+    navigateUpKeyAriaLabel?: string
+    navigateDownKeyAriaLabel?: string
+    closeText?: string
+    closeKeyAriaLabel?: string
+  }
+}
+
+const defaultTranslations: { modal: ModalTranslations } = {
+  modal: {
+    displayDetails: 'Display detailed list',
+    resetButtonTitle: 'Reset search',
+    backButtonTitle: 'Close search',
+    noResultsText: 'No results for',
+    footer: {
+      selectText: 'to select',
+      selectKeyAriaLabel: 'enter',
+      navigateText: 'to navigate',
+      navigateUpKeyAriaLabel: 'up arrow',
+      navigateDownKeyAriaLabel: 'down arrow',
+      closeText: 'to close',
+      closeKeyAriaLabel: 'escape'
+    }
+  }
+}
+
+const translate = createSearchTranslate(defaultTranslations)
+
+// Back
+
+onMounted(() => {
+  // Prevents going to previous site
+  window.history.pushState(null, '', null)
+})
+
+useEventListener('popstate', (event) => {
+  event.preventDefault()
+  emit('close')
+})
+
+/** Lock body */
+const isLocked = useScrollLock(inBrowser ? document.body : null)
+
+onMounted(() => {
+  nextTick(() => {
+    isLocked.value = true
+    nextTick().then(() => activate())
+  })
+})
+
+onBeforeUnmount(() => {
+  isLocked.value = false
+})
+
+function resetSearch() {
+  filterText.value = ''
+  nextTick().then(() => focusSearchInput(false))
+}
+
+function formMarkRegex(terms: Set<string>) {
+  return new RegExp(
+    [...terms]
+      .sort((a, b) => b.length - a.length)
+      .map((term) => `(${escapeRegExp(term)})`)
+      .join('|'),
+    'gi'
+  )
+}
+
+function onMouseMove(e: MouseEvent) {
+  if (!disableMouseOver.value) return
+  const el = (e.target as HTMLElement)?.closest<HTMLAnchorElement>('.result')
+  const index = Number.parseInt(el?.dataset.index!)
+  if (index >= 0 && index !== selectedIndex.value) {
+    selectedIndex.value = index
+  }
+  disableMouseOver.value = false
+}
+</script>
+
+<template>
+  <Teleport to="body">
+    <div
+      ref="el"
+      role="button"
+      :aria-owns="results?.length ? 'localsearch-list' : undefined"
+      aria-expanded="true"
+      aria-haspopup="listbox"
+      aria-labelledby="localsearch-label"
+      class="VPLocalSearchBox"
+    >
+      <div class="backdrop" @click="$emit('close')" />
+
+      <div class="shell">
+        <form
+          class="search-bar"
+          @pointerup="onSearchBarClick($event)"
+          @submit.prevent=""
+        >
+          <label
+            :title="buttonText"
+            id="localsearch-label"
+            for="localsearch-input"
+          >
+            <span aria-hidden="true" class="vpi-search search-icon local-search-icon" />
+          </label>
+          <div class="search-actions before">
+            <button
+              class="back-button"
+              :title="translate('modal.backButtonTitle')"
+              @click="$emit('close')"
+            >
+              <span class="vpi-arrow-left local-search-icon" />
+            </button>
+          </div>
+          <input
+            ref="searchInput"
+            v-model="filterText"
+            :aria-activedescendant="selectedIndex > -1 ? ('localsearch-item-' + selectedIndex) : undefined"
+            aria-autocomplete="both"
+            :aria-controls="results?.length ? 'localsearch-list' : undefined"
+            aria-labelledby="localsearch-label"
+            autocapitalize="off"
+            autocomplete="off"
+            autocorrect="off"
+            class="search-input"
+            id="localsearch-input"
+            enterkeyhint="go"
+            maxlength="64"
+            :placeholder="buttonText"
+            spellcheck="false"
+            type="search"
+          />
+          <div class="search-actions">
+            <button
+              v-if="!disableDetailedView"
+              class="toggle-layout-button"
+              type="button"
+              :class="{ 'detailed-list': showDetailedList }"
+              :title="translate('modal.displayDetails')"
+              @click="
+                selectedIndex > -1 && (showDetailedList = !showDetailedList)
+              "
+            >
+              <span class="vpi-layout-list local-search-icon" />
+            </button>
+
+            <button
+              class="clear-button"
+              type="reset"
+              :disabled="disableReset"
+              :title="translate('modal.resetButtonTitle')"
+              @click="resetSearch"
+            >
+              <span class="vpi-delete local-search-icon" />
+            </button>
+          </div>
+        </form>
+
+        <ul
+          ref="resultsEl"
+          :id="results?.length ? 'localsearch-list' : undefined"
+          :role="results?.length ? 'listbox' : undefined"
+          :aria-labelledby="results?.length ? 'localsearch-label' : undefined"
+          class="results"
+          @mousemove="onMouseMove"
+        >
+          <li
+            v-for="(p, index) in results"
+            :key="p.id"
+            :id="'localsearch-item-' + index"
+            :aria-selected="selectedIndex === index ? 'true' : 'false'"
+            role="option"
+          >
+            <a
+              :href="p.id"
+              class="result"
+              :class="{
+                selected: selectedIndex === index
+              }"
+              :aria-label="[...p.titles, p.title].join(' > ')"
+              @mouseenter="!disableMouseOver && (selectedIndex = index)"
+              @focusin="selectedIndex = index"
+              @click="$emit('close')"
+              :data-index="index"
+            >
+              <div>
+                <div class="titles">
+                  <span class="title-icon">#</span>
+                  <span
+                    v-for="(t, index) in p.titles"
+                    :key="index"
+                    class="title"
+                  >
+                    <span class="text" v-html="t" />
+                    <span class="vpi-chevron-right local-search-icon" />
+                  </span>
+                  <span class="title main">
+                    <span class="text" v-html="p.title" />
+                  </span>
+                </div>
+
+                <div v-if="showDetailedList" class="excerpt-wrapper">
+                  <div v-if="p.text" class="excerpt" inert>
+                    <div class="vp-doc" v-html="p.text" />
+                  </div>
+                  <div class="excerpt-gradient-bottom" />
+                  <div class="excerpt-gradient-top" />
+                </div>
+              </div>
+            </a>
+          </li>
+          <li v-if="loadingIndex" class="index-loading">
+            {{ localeIndex === 'root' ? '正在加载搜索索引…' : 'Loading search index…' }}
+          </li>
+          <li v-if="excerptLoading" class="index-loading">
+            {{ localeIndex === 'root' ? '正在生成摘要…' : 'Generating excerpts…' }}
+          </li>
+          <li
+            v-if="filterText && !results.length && enableNoResults"
+            class="no-results"
+          >
+            {{ translate('modal.noResultsText') }} "<strong>{{ filterText }}</strong
+            >"
+          </li>
+        </ul>
+
+        <div class="search-keyboard-shortcuts">
+          <span>
+            <kbd :aria-label="translate('modal.footer.navigateUpKeyAriaLabel')">
+              <span class="vpi-arrow-up navigate-icon" />
+            </kbd>
+            <kbd :aria-label="translate('modal.footer.navigateDownKeyAriaLabel')">
+              <span class="vpi-arrow-down navigate-icon" />
+            </kbd>
+            {{ translate('modal.footer.navigateText') }}
+          </span>
+          <span>
+            <kbd :aria-label="translate('modal.footer.selectKeyAriaLabel')">
+              <span class="vpi-corner-down-left navigate-icon" />
+            </kbd>
+            {{ translate('modal.footer.selectText') }}
+          </span>
+          <span>
+            <kbd :aria-label="translate('modal.footer.closeKeyAriaLabel')">esc</kbd>
+            {{ translate('modal.footer.closeText') }}
+          </span>
+        </div>
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style scoped>
+.VPLocalSearchBox {
+  position: fixed;
+  z-index: 100;
+  inset: 0;
+  display: flex;
+}
+
+.backdrop {
+  position: absolute;
+  inset: 0;
+  background: var(--vp-backdrop-bg-color);
+  transition: opacity 0.5s;
+}
+
+.shell {
+  position: relative;
+  padding: 12px;
+  margin: 64px auto;
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  background: var(--vp-local-search-bg);
+  width: min(100vw - 60px, 900px);
+  height: min-content;
+  max-height: min(100vh - 128px, 900px);
+  border-radius: 6px;
+}
+
+@media (max-width: 767px) {
+  .shell {
+    margin: 0;
+    width: 100vw;
+    height: 100vh;
+    max-height: none;
+    border-radius: 0;
+  }
+}
+
+.search-bar {
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 4px;
+  display: flex;
+  align-items: center;
+  padding: 0 12px;
+  cursor: text;
+}
+
+@media (max-width: 767px) {
+  .search-bar {
+    padding: 0 8px;
+  }
+}
+
+.search-bar:focus-within {
+  border-color: var(--vp-c-brand-1);
+}
+
+.local-search-icon {
+  display: block;
+  font-size: 18px;
+}
+
+.navigate-icon {
+  display: block;
+  font-size: 14px;
+}
+
+.search-icon {
+  margin: 8px;
+}
+
+@media (max-width: 767px) {
+  .search-icon {
+    display: none;
+  }
+}
+
+.search-input {
+  padding: 6px 12px;
+  font-size: inherit;
+  width: 100%;
+}
+
+@media (max-width: 767px) {
+  .search-input {
+    padding: 6px 4px;
+  }
+}
+
+.search-actions {
+  display: flex;
+  gap: 4px;
+}
+
+@media (any-pointer: coarse) {
+  .search-actions {
+    gap: 8px;
+  }
+}
+
+@media (min-width: 769px) {
+  .search-actions.before {
+    display: none;
+  }
+}
+
+.search-actions button {
+  padding: 8px;
+}
+
+.search-actions button:not([disabled]):hover,
+.toggle-layout-button.detailed-list {
+  color: var(--vp-c-brand-1);
+}
+
+.search-actions button.clear-button:disabled {
+  opacity: 0.37;
+}
+
+.search-keyboard-shortcuts {
+  font-size: 0.8rem;
+  opacity: 75%;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 16px;
+  line-height: 14px;
+}
+
+.search-keyboard-shortcuts span {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+@media (max-width: 767px) {
+  .search-keyboard-shortcuts {
+    display: none;
+  }
+}
+
+.search-keyboard-shortcuts kbd {
+  background: rgba(128, 128, 128, 0.1);
+  border-radius: 4px;
+  padding: 3px 6px;
+  min-width: 24px;
+  display: inline-block;
+  text-align: center;
+  vertical-align: middle;
+  border: 1px solid rgba(128, 128, 128, 0.15);
+  box-shadow: 0 2px 2px 0 rgba(0, 0, 0, 0.1);
+}
+
+.results {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  overflow-x: hidden;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+}
+
+.result {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  border-radius: 4px;
+  transition: none;
+  line-height: 1rem;
+  border: solid 2px var(--vp-local-search-result-border);
+  outline: none;
+}
+
+.result > div {
+  margin: 12px;
+  width: 100%;
+  overflow: hidden;
+}
+
+@media (max-width: 767px) {
+  .result > div {
+    margin: 8px;
+  }
+}
+
+.titles {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+  position: relative;
+  z-index: 1001;
+  padding: 2px 0;
+}
+
+.title {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.title.main {
+  font-weight: 500;
+}
+
+.title-icon {
+  opacity: 0.5;
+  font-weight: 500;
+  color: var(--vp-c-brand-1);
+}
+
+.title svg {
+  opacity: 0.5;
+}
+
+.result.selected {
+  --vp-local-search-result-bg: var(--vp-local-search-result-selected-bg);
+  border-color: var(--vp-local-search-result-selected-border);
+}
+
+.excerpt-wrapper {
+  position: relative;
+}
+
+.excerpt {
+  opacity: 50%;
+  pointer-events: none;
+  max-height: 140px;
+  overflow: hidden;
+  position: relative;
+  margin-top: 4px;
+}
+
+.result.selected .excerpt {
+  opacity: 1;
+}
+
+.excerpt :deep(*) {
+  font-size: 0.8rem !important;
+  line-height: 130% !important;
+}
+
+.titles :deep(mark),
+.excerpt :deep(mark) {
+  background-color: var(--vp-local-search-highlight-bg);
+  color: var(--vp-local-search-highlight-text);
+  border-radius: 2px;
+  padding: 0 2px;
+}
+
+.excerpt :deep(.vp-code-group) .tabs {
+  display: none;
+}
+
+.excerpt :deep(.vp-code-group) div[class*='language-'] {
+  border-radius: 8px !important;
+}
+
+.excerpt-gradient-bottom {
+  position: absolute;
+  bottom: -1px;
+  left: 0;
+  width: 100%;
+  height: 8px;
+  background: linear-gradient(transparent, var(--vp-local-search-result-bg));
+  z-index: 1000;
+}
+
+.excerpt-gradient-top {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 8px;
+  background: linear-gradient(var(--vp-local-search-result-bg), transparent);
+  z-index: 1000;
+}
+
+.result.selected .titles,
+.result.selected .title-icon {
+  color: var(--vp-c-brand-1) !important;
+}
+
+.index-loading {
+  font-size: 0.9rem;
+  text-align: center;
+  padding: 12px;
+  opacity: 0.75;
+}
+
+.no-results {
+  font-size: 0.9rem;
+  text-align: center;
+  padding: 12px;
+}
+
+svg {
+  flex: none;
+}
+</style>
diff --git a/site/.vitepress/theme/local-search-backend.ts b/site/.vitepress/theme/local-search-backend.ts
new file mode 100644
index 000000000..fa2873f64
--- /dev/null
+++ b/site/.vitepress/theme/local-search-backend.ts
@@ -0,0 +1,130 @@
+// 搜索后端封装(vitepress theme 覆盖件,配套 VPLocalSearchBox.vue)。
+// 优先用 Web Worker 跑索引构建 + 查询;worker 不可用(老浏览器/被 CSP 拦)
+// 或 worker 初始化失败时,自动回退到 VitePress 原行为:主线程 MiniSearch。
+//
+// 实例是模块级单例:搜索盒每次开关不重建、不丢已解析的索引,重新打开
+// 搜索时不用再付一次解析成本。
+import MiniSearch, { type Options, type SearchResult } from 'minisearch'
+
+// 与 worker 侧、VPLocalSearchBox 的展示条数一致
+const RESULT_LIMIT = 16
+
+export interface SearchBackend {
+  init(json: string, options: Options<any>): Promise<void>
+  search(query: string): Promise<SearchResult[]>
+}
+
+let shared: SearchBackend | null = null
+
+export function getSearchBackend(): SearchBackend {
+  if (!shared) {
+    shared = createWorkerBackend() ?? createMainThreadBackend()
+  }
+  return shared
+}
+
+function createWorkerBackend(): SearchBackend | null {
+  // 该模块只会在浏览器挂载的组件里被调用,这里再兜一道 SSR/环境守卫
+  if (import.meta.env.SSR || typeof Worker === 'undefined') return null
+  try {
+    return new WorkerSearchBackend()
+  } catch {
+    return null
+  }
+}
+
+class WorkerSearchBackend implements SearchBackend {
+  private worker: Worker
+  private dead = false
+  // worker 初始化失败后改走的主线程索引(即 VitePress 原行为)
+  private fallbackIndex: MiniSearch<any> | null = null
+  private msgId = 0
+  private initWaiters = new Map<
+    number,
+    { resolve: () => void; reject: (err: unknown) => void }
+  >()
+  private searchWaiters = new Map<number, (results: SearchResult[]) => void>()
+
+  constructor() {
+    this.worker = new Worker(
+      new URL('./local-search-worker.ts', import.meta.url),
+      { type: 'module' }
+    )
+    this.worker.onmessage = (e: MessageEvent) => this.onMessage(e.data)
+    this.worker.onerror = () => this.drainWaiters()
+  }
+
+  private onMessage(msg: {
+    type: 'ready' | 'error' | 'results'
+    id: number
+    results?: SearchResult[]
+    message?: string
+  }) {
+    if (msg.type === 'ready' || msg.type === 'error') {
+      const waiter = this.initWaiters.get(msg.id)
+      this.initWaiters.delete(msg.id)
+      if (msg.type === 'ready') waiter?.resolve()
+      else waiter?.reject(new Error(msg.message))
+    } else if (msg.type === 'results') {
+      const resolve = this.searchWaiters.get(msg.id)
+      this.searchWaiters.delete(msg.id)
+      resolve?.(msg.results ?? [])
+    }
+  }
+
+  // worker 崩溃/加载失败:在途请求一律收尾,别让组件悬挂
+  private drainWaiters() {
+    this.dead = true
+    for (const { reject } of this.initWaiters.values()) {
+      reject(new Error('search worker crashed'))
+    }
+    this.initWaiters.clear()
+    for (const resolve of this.searchWaiters.values()) resolve([])
+    this.searchWaiters.clear()
+  }
+
+  async init(json: string, options: Options<any>): Promise<void> {
+    // 已经在走主线程回退了,就不再碰 worker
+    if (this.dead) {
+      this.fallbackIndex = MiniSearch.loadJSON(json, options)
+      return
+    }
+    const id = ++this.msgId
+    const ready = new Promise<void>((resolve, reject) => {
+      this.initWaiters.set(id, { resolve, reject })
+    })
+    this.worker.postMessage({ type: 'init', id, json, options })
+    try {
+      await ready
+      this.fallbackIndex = null
+    } catch {
+      // worker 初始化失败:同一份 json 落回主线程,行为退回 VitePress 原状
+      this.dead = true
+      this.fallbackIndex = MiniSearch.loadJSON(json, options)
+    }
+  }
+
+  async search(query: string): Promise<SearchResult[]> {
+    if (this.fallbackIndex) {
+      return this.fallbackIndex.search(query).slice(0, RESULT_LIMIT)
+    }
+    if (this.dead) return []
+    const id = ++this.msgId
+    return new Promise((resolve) => {
+      this.searchWaiters.set(id, resolve)
+      this.worker.postMessage({ type: 'search', id, query })
+    })
+  }
+}
+
+function createMainThreadBackend(): SearchBackend {
+  let index: MiniSearch<any> | null = null
+  return {
+    async init(json, options) {
+      index = MiniSearch.loadJSON(json, options)
+    },
+    async search(query) {
+      return index ? index.search(query).slice(0, RESULT_LIMIT) : []
+    },
+  }
+}
diff --git a/site/.vitepress/theme/local-search-worker.ts b/site/.vitepress/theme/local-search-worker.ts
new file mode 100644
index 000000000..c83760b56
--- /dev/null
+++ b/site/.vitepress/theme/local-search-worker.ts
@@ -0,0 +1,31 @@
+// 本地搜索 worker(vitepress theme 覆盖件,配套 VPLocalSearchBox.vue)。
+// 全站索引是一块 13MB 级的 JSON(zh),原先 JSON.parse + MiniSearch 重建 +
+// 每次击键的查询全在主线程,搜索一开页面就冻住(issue #156)。这里把这些
+// 重活全部搬进 worker,主线程只收结果。
+//
+// 协议(请求按发送顺序串行处理,响应带 id 原路返回):
+//   { type: 'init',   id, json, options } -> { type: 'ready' | 'error', id }
+//   { type: 'search', id, query }         -> { type: 'results', id, results }
+import MiniSearch from 'minisearch'
+
+// 与 VPLocalSearchBox 的展示条数一致;主线程侧不再重复截断
+const RESULT_LIMIT = 16
+
+let index: MiniSearch<any> | null = null
+
+self.onmessage = (e: MessageEvent) => {
+  const msg = e.data
+  if (msg.type === 'init') {
+    try {
+      index = MiniSearch.loadJSON(msg.json, msg.options)
+      self.postMessage({ type: 'ready', id: msg.id })
+    } catch (err) {
+      index = null
+      self.postMessage({ type: 'error', id: msg.id, message: String(err) })
+    }
+  } else if (msg.type === 'search') {
+    // init 尚未完成时收到查询:回空结果,主线程有 loading 态兜底
+    const results = index ? index.search(msg.query).slice(0, RESULT_LIMIT) : []
+    self.postMessage({ type: 'results', id: msg.id, results })
+  }
+}
diff --git a/site/.vitepress/theme/vitepress-deep-modules.d.ts b/site/.vitepress/theme/vitepress-deep-modules.d.ts
new file mode 100644
index 000000000..a04adbf2c
--- /dev/null
+++ b/site/.vitepress/theme/vitepress-deep-modules.d.ts
@@ -0,0 +1,44 @@
+// VPLocalSearchBox.vue 覆盖件用到的 vitepress 内部模块的手写最小类型。
+// 这些文件经 vitepress 的 "./dist/*" exports 深导入可达,但包里没有随附
+// .d.ts;类型声明只为编辑器/TS 解析,不参与构建产物。
+declare module '@localSearchIndex' {
+  const localSearchIndex: Record<
+    string,
+    () => Promise<{ default: string }> | undefined
+  >
+  export default localSearchIndex
+}
+
+declare module 'vitepress/dist/client/app/utils.js' {
+  export function pathToFile(path: string): string | null
+}
+
+declare module 'vitepress/dist/client/shared.js' {
+  export function escapeRegExp(str: string): string
+}
+
+declare module 'vitepress/dist/client/theme-default/support/lru.js' {
+  export class LRUCache<K, V> {
+    constructor(max?: number)
+    get(key: K): V | undefined
+    set(key: K, value: V): void
+    clear(): void
+  }
+}
+
+declare module 'vitepress/dist/client/theme-default/support/translation.js' {
+  export function createSearchTranslate<T extends object>(
+    defaultTranslations: T
+  ): (key: string) => string
+}
+
+declare module 'mark.js/src/vanilla.js' {
+  export default class Mark {
+    constructor(root: HTMLElement)
+    unmark(options: { done?: () => void }): void
+    markRegExp(
+      regex: RegExp,
+      options: { done?: () => void; acrossElements?: boolean }
+    ): void
+  }
+}