@vuepress-plume/plugin-search 1.0.0-rc.211 → 1.0.0-rc.213

package/dist/client/components/Search.vue

@@ -2,12 +2,15 @@
 import type { SearchBoxLocales, SearchOptions } from '../../shared/index.js'
 import { onKeyStroke } from '@vueuse/core'
 import {
+  computed,
   defineAsyncComponent,
   ref,
+  toRef,
 } from 'vue'
+import { useLocale } from '../composables/index.js'
 import SearchButton from './SearchButton.vue'
 
-defineProps<{
+const props = defineProps<{
   locales: SearchBoxLocales
   options: SearchOptions
 }>()
@@ -16,15 +19,42 @@ const SearchBox = defineAsyncComponent(() => import('./SearchBox.vue'))
 
 const showSearch = ref(false)
 
+const locale = useLocale(toRef(() => props.locales))
+
+/**
+ * Text shown when JavaScript is disabled.
+ *
+ * 禁用 JavaScript 时展示的提示文本。
+ *
+ * `<noscript>` 仅在脚本被禁用时渲染，且必须是纯文本：启用脚本时浏览器会把
+ * 其中的内容当作原始文本，若包含元素或 HTML 实体会造成水合不匹配。
+ * `<noscript>` only renders with scripting disabled, and must stay plain text:
+ * with scripting enabled browsers parse its content as raw text, so elements or
+ * HTML entities would cause a hydration mismatch.
+ */
+const noscriptText = computed(
+  () => locale.value.noscriptText || 'Search is unavailable without JavaScript.',
+)
+
 onKeyStroke('k', (event) => {
-  if (event.ctrlKey || event.metaKey) {
+  // 在输入框 / 可编辑区域内不劫持 Ctrl/Cmd + K（如 macOS 的删除至行尾）。
+  // Do not hijack Ctrl/Cmd + K while editing content (e.g. macOS delete-to-end-of-line).
+  if ((event.ctrlKey || event.metaKey) && !isEditingContent(event)) {
     event.preventDefault()
     showSearch.value = true
   }
 })
 
 onKeyStroke('/', (event) => {
-  if (!isEditingContent(event)) {
+  // 仅在无修饰键且不在编辑内容时劫持，避免与浏览器/系统组合键冲突。
+  // Only hijack without modifiers and outside editable content to avoid clashing
+  // with browser/system shortcuts.
+  if (
+    !event.ctrlKey
+    && !event.metaKey
+    && !event.altKey
+    && !isEditingContent(event)
+  ) {
     event.preventDefault()
     showSearch.value = true
   }
@@ -55,6 +85,8 @@ function isEditingContent(event: KeyboardEvent): boolean {
     <div id="local-search">
       <SearchButton :locales="locales" @click="showSearch = true" />
     </div>
+
+    <noscript>{{ noscriptText }}</noscript>
   </div>
 </template>
 
@@ -64,6 +96,14 @@ function isEditingContent(event: KeyboardEvent): boolean {
   align-items: center;
 }
 
+/* 仅在禁用 JavaScript 时可见的降级提示。
+   Fallback hint that is only visible when JavaScript is disabled. */
+.search-wrapper noscript {
+  font-size: 13px;
+  line-height: 1.4;
+  color: var(--vp-c-text-2);
+}
+
 @media (min-width: 768px) {
   .search-wrapper {
     flex-grow: 1;

package/dist/client/components/SearchBox.vue

@@ -25,8 +25,8 @@ import {
   watch,
 } from 'vue'
 import { usePageLang, useRouteLocale, useRouter, withBase } from 'vuepress/client'
-import { useLocale, useSearchIndex } from '../composables/index.js'
-import { LRUCache } from '../utils/index.js'
+import { createTokenizer } from '../../shared/index.js'
+import { loadSearchIndexJSON, useLocale } from '../composables/index.js'
 import BackIcon from './icons/BackIcon.vue'
 import ClearIcon from './icons/ClearIcon.vue'
 import SearchIcon from './icons/SearchIcon.vue'
@@ -47,12 +47,9 @@ const lang = usePageLang()
 const el = shallowRef<HTMLElement>()
 const resultsEl = shallowRef<HTMLElement>()
 
-const searchIndexData = useSearchIndex()
-
 interface Result {
   title: string
   titles: string[]
-  text?: string
 }
 
 const { activate } = useFocusTrap(el, { immediate: true })
@@ -62,17 +59,69 @@ const isSearching = ref(false)
 
 const showSearchSpinner = computed(() => isSearchIndexLoading.value || isSearching.value)
 
-const searchIndex = computedAsync(async () => {
-  let tokenize: ((str: string) => string[]) | undefined
-  if (typeof Intl.Segmenter !== 'undefined') {
-    const segmenter = new Intl.Segmenter(lang.value, { granularity: 'word' })
-    tokenize = str => Array.from(segmenter.segment(str)).map(s => s.segment)
-  }
+/**
+ * Visible error message when the search index is missing or fails to load.
+ *
+ * 搜索索引缺失或加载失败时显示的可见提示。
+ */
+const searchIndexError = ref('')
+
+const searchIndexErrorText = computed(() =>
+  locale.value.searchIndexErrorText || 'Failed to load the search index.',
+)
 
-  return markRaw(
-    MiniSearch.loadJSON<Result>(
-      (await searchIndexData.value[routeLocale.value]?.())?.default,
-      {
+/**
+ * Create an empty index used as a fallback when the index is missing or fails
+ * to load, so searching returns an empty result set instead of throwing.
+ *
+ * 创建空索引，在索引缺失或加载失败时兜底，使检索返回空结果而不是抛出异常。
+ */
+function createEmptyIndex(): MiniSearch<Result> {
+  return new MiniSearch<Result>({
+    fields: ['title', 'titles', 'text'],
+    storeFields: ['title', 'titles'],
+  })
+}
+
+const searchIndex = computedAsync(async (onCancel) => {
+  // 标记本次求值是否已被新一轮加载取代（例如 HMR 更新索引）。
+  // 过期任务不得再写入错误状态，否则有效结果旁会残留加载失败提示。
+  //
+  // Mark this evaluation as stale (e.g. superseded by a newer load during HMR).
+  // A stale task must not write the error state, otherwise a load failure message
+  // would persist next to valid results.
+  let canceled = false
+  onCancel(() => {
+    canceled = true
+  })
+
+  searchIndexError.value = ''
+
+  // 使用与 Node 端建索引时完全一致的分词策略，避免两端词元不匹配导致检索失效。
+  // Use the same tokenizer as the node build side so query tokens always match the index.
+  const tokenize = createTokenizer(lang.value)
+
+  try {
+    // 分片索引在客户端按片合并并让出主线程，避免大索引长时间阻塞渲染。
+    // Sharded indexes are merged piece by piece on the client, yielding to the main
+    // thread, so a large index never blocks rendering for long.
+    const indexJson = await loadSearchIndexJSON(routeLocale.value)
+
+    // 当前语言缺少索引文件时回退到空索引，并给出可见提示，避免静默无结果。
+    // Fall back to an empty index and show a visible message when the locale has no index.
+    if (!indexJson) {
+      if (!canceled)
+        searchIndexError.value = searchIndexErrorText.value
+      return markRaw(createEmptyIndex())
+    }
+
+    // 使用公开的异步反序列化 API（`loadJSAsync` 为 `@ignore` 的内部 API），
+    // 它在批次之间让出主线程，避免大索引同步解析长时间阻塞。
+    // Use the public async deserialization API (`loadJSAsync` is an `@ignore`d
+    // internal API). It yields to the main thread between batches, so a large index
+    // never blocks rendering for long.
+    return markRaw(
+      await MiniSearch.loadJSONAsync<Result>(indexJson, {
         fields: ['title', 'titles', 'text'],
         storeFields: ['title', 'titles'],
         searchOptions: {
@@ -83,9 +132,15 @@ const searchIndex = computedAsync(async () => {
         },
         ...options.miniSearch?.searchOptions,
         ...options.miniSearch?.options,
-      },
-    ),
-  )
+      }),
+    )
+  }
+  catch (error) {
+    console.error('[plugin-search] failed to load the search index:', error)
+    if (!canceled)
+      searchIndexError.value = searchIndexErrorText.value
+    return markRaw(createEmptyIndex())
+  }
 }, undefined, isSearchIndexLoading)
 
 const disableQueryPersistence = computed(() =>
@@ -111,16 +166,9 @@ const mark = computedAsync(async () => {
   return markRaw(new Mark(resultsEl.value))
 }, null)
 
-const cache = new LRUCache<string, Map<string, string>>(64) // 64 files
-
 watchDebounced(
   () => [searchIndex.value, filterText.value] as const,
-  async ([index, filterTextValue], old, onCleanup) => {
-    if (old?.[0] !== index) {
-      // in case of hmr
-      cache.clear()
-    }
-
+  async ([index, filterTextValue], _old, onCleanup) => {
     let canceled = false
     onCleanup(() => {
       canceled = true
@@ -140,16 +188,10 @@ watchDebounced(
     enableNoResults.value = true
 
     const terms = new Set<string>()
-
-    results.value = results.value.map((r) => {
-      const [id, anchor] = r.id.split('#')
-      const map = cache.get(id)
-      const text = map?.get(anchor) ?? ''
-      for (const term in r.match)
+    for (const result of results.value) {
+      for (const term in result.match)
         terms.add(term)
-
-      return { ...r, text }
-    })
+    }
 
     await nextTick()
     if (canceled)
@@ -255,6 +297,30 @@ onKeyStroke(['n', 'N'], (event) => {
 
 const router = useRouter()
 
+/**
+ * Whether the browser back button already closed the search box.
+ *
+ * 浏览器后退键是否已关闭搜索框。
+ *
+ * When true the extra history entry created on mount has been consumed, so the
+ * unmount handler must not roll history back again.
+ *
+ * 为 true 时说明挂载时压入的额外历史条目已被消费，卸载时不应再回退历史。
+ */
+let closedByPopstate = false
+
+/**
+ * Whether the search box is being closed because a result is being opened.
+ *
+ * 搜索框是否因跳转到搜索结果而关闭。
+ *
+ * In that case the URL must stay on the target page, so history must not be
+ * rolled back on unmount.
+ *
+ * 此时 URL 必须停留在目标页面，卸载时不能回退历史。
+ */
+let navigatingToResult = false
+
 onKeyStroke('Enter', (e) => {
   if (e.isComposing)
     return
@@ -269,7 +335,11 @@ onKeyStroke('Enter', (e) => {
   }
 
   if (selectedPackage) {
-    router.push(selectedPackage.id)
+    navigatingToResult = true
+    // 用 replace 顶替挂载时 pushState 的临时历史条目，避免从结果页返回时多一次 Back。
+    // Replace the temporary history entry pushed on mount, so returning from the
+    // result page does not require an extra Back press.
+    router.replace(selectedPackage.id)
     emit('close')
   }
 })
@@ -287,6 +357,7 @@ onMounted(() => {
 
 useEventListener('popstate', (event) => {
   event.preventDefault()
+  closedByPopstate = true
   emit('close')
 })
 
@@ -302,6 +373,15 @@ onMounted(() => {
 
 onBeforeUnmount(() => {
   isLocked.value = false
+  // 配对挂载时的 pushState，避免反复开关搜索框累积历史条目。
+  // 若该条目已被浏览器后退键（popstate）消费，或正在跳转到搜索结果，则不能回退。
+  //
+  // Pair the pushState made on mount so repeated open/close does not pile up
+  // history entries. Skip the rollback when the entry was already consumed by
+  // the browser back button (popstate), or when opening a result (the URL must
+  // stay on the target page).
+  if (!closedByPopstate && !navigatingToResult)
+    window.history.back()
 })
 
 function resetSearch() {
@@ -325,7 +405,10 @@ function formMarkRegex(terms: Set<string>) {
 
 function selectedClick(e: MouseEvent, p: SearchResult & Result) {
   e.preventDefault()
-  router.push(p.id)
+  navigatingToResult = true
+  // 同 Enter 键路径：replace 消费掉挂载时压入的临时历史条目。
+  // Same as the Enter path: replace consumes the temp entry pushed on mount.
+  router.replace(p.id)
   emit('close')
 }
 </script>
@@ -338,7 +421,7 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
       :aria-owns="results?.length ? 'localsearch-list' : undefined"
       aria-expanded="true"
       aria-haspopup="listbox"
-      aria-labelledby="mini-search-label"
+      aria-labelledby="localsearch-label"
       class="VPLocalSearchBox"
     >
       <div class="backdrop" @click="$emit('close')" />
@@ -447,7 +530,14 @@ function selectedClick(e: MouseEvent, p: SearchResult & Result) {
             </a>
           </li>
           <li
-            v-if="filterText && !results.length && enableNoResults"
+            v-if="searchIndexError"
+            class="no-results error"
+            role="alert"
+          >
+            {{ searchIndexError }}
+          </li>
+          <li
+            v-else-if="filterText && !results.length && enableNoResults"
             class="no-results"
           >
             {{ locale.noResultsText }} "<strong>{{ filterText }}</strong>"
@@ -815,4 +905,8 @@ svg {
   font-size: 0.9rem;
   text-align: center;
 }
+
+.no-results.error {
+  color: var(--vp-c-danger-1, #b8272c);
+}
 </style>

package/dist/client/composables/index.d.ts

@@ -14,21 +14,36 @@ import {SearchBoxLocales, SearchLocaleOptions} from '../../shared/index.js'
 export declare function useLocale(
   locales: MaybeRef<SearchBoxLocales>,
 ): ComputedRef<Partial<SearchLocaleOptions>>
+/**
+ * Shape of a dynamically imported index module.
+ *
+ * 动态导入的索引模块的形状。
+ *
+ * Large locales are split into shards: the default export then holds the index
+ * metadata (with an empty `index`), and `shards` exposes lazy loaders for the
+ * remaining term entries.
+ *
+ * 较大的语言会被拆分为分片：此时默认导出承载索引元数据（`index` 为空），
+ * `shards` 则提供其余词元条目的延迟加载函数。
+ */
+export interface SearchIndexModule {
+  /** Serialized index JSON, or the index metadata when sharded / 序列化索引 JSON；分片时为索引元数据 */
+  default: string
+  /** Lazy loaders of the remaining shards / 其余分片的延迟加载函数 */
+  shards?: (() => Promise<{
+    default: string
+  }>)[]
+}
 /**
  * Type definition for search index data.
  *
  * 搜索索引数据的类型定义。
  *
- * Maps locale paths to functions that load the corresponding search index.
+ * Maps locale paths to functions that load the corresponding search index module.
  *
- * 将语言路径映射到加载相应搜索索引的函数。
+ * 将语言路径映射到加载相应搜索索引模块的函数。
  */
-type SearchIndexData = Record<
-  string,
-  () => Promise<{
-    default: string
-  }>
->
+export type SearchIndexData = Record<string, () => Promise<SearchIndexModule>>
 /**
  * Get the search index data for all locales.
  *
@@ -37,6 +52,29 @@ type SearchIndexData = Record<
  * @returns Shallow ref to the search index data / 搜索索引数据的浅层引用
  * @example
  * const indexData = useSearchIndex()
- * const localeIndex = await indexData.value['/zh/']()
+ * const loadModule = indexData.value['/zh/']
  */
 export declare function useSearchIndex(): ShallowRef<SearchIndexData>
+/**
+ * Load and assemble the JSON-serialized search index of a locale.
+ *
+ * 加载并组装某个语言的 JSON 序列化搜索索引。
+ *
+ * The returned string can be passed to `MiniSearch.loadJSONAsync()`, which
+ * deserializes the index in batches without blocking the main thread.
+ *
+ * 返回的字符串可直接交给 `MiniSearch.loadJSONAsync()`，
+ * 它会分批反序列化索引，避免阻塞主线程。
+ *
+ * Sharded indexes are loaded in parallel and then merged one shard at a time,
+ * yielding to the main thread between shards. This keeps the first paint and
+ * input handling responsive while a large index is being assembled.
+ *
+ * 分片索引会并行加载，再逐片合并，并在分片之间让出主线程。
+ * 这样在组装大索引时仍能保持首屏渲染与输入的响应性。
+ *
+ * @param locale - Locale path (e.g. `/`, `/zh/`) / 语言路径
+ * @returns Serialized index JSON, or `undefined` when the locale has no index /
+ *   序列化索引 JSON；该语言没有索引时返回 `undefined`
+ */
+export declare function loadSearchIndexJSON(locale: string): Promise<string | undefined>

package/dist/client/composables/index.js

@@ -8,6 +8,8 @@ const defaultLocales = {
     resetButtonTitle: 'Reset search',
     backButtonTitle: 'Close search',
     noResultsText: 'No results for',
+    searchIndexErrorText: 'Failed to load the search index.',
+    noscriptText: 'Search is unavailable without JavaScript.',
     footer: {
       selectText: 'to select',
       selectKeyAriaLabel: 'enter',
@@ -36,9 +38,28 @@ const searchIndexData = shallowRef(searchIndex)
 function useSearchIndex() {
   return searchIndexData
 }
+
+function yieldToMainThread() {
+  return new Promise((resolve) => setTimeout(resolve))
+}
+
+async function loadSearchIndexJSON(locale) {
+  const loadIndexModule = searchIndexData.value[locale]
+  if (!loadIndexModule) return void 0
+  const indexModule = await loadIndexModule()
+  if (!indexModule.shards?.length) return indexModule.default
+  const serialized = JSON.parse(indexModule.default)
+  const shards = await Promise.all(indexModule.shards.map((loadShard) => loadShard()))
+  for (const shard of shards) {
+    const entries = JSON.parse(shard.default)
+    for (const entry of entries) serialized.index.push(entry)
+    await yieldToMainThread()
+  }
+  return JSON.stringify(serialized)
+}
 if (__VUEPRESS_DEV__ && (import.meta.webpackHot || import.meta.hot))
   __VUE_HMR_RUNTIME__.updateSearchIndex = (data) => {
     searchIndexData.value = data
   }
 
-export {useLocale, useSearchIndex}
+export {loadSearchIndexJSON, useLocale, useSearchIndex}

package/dist/client/index.d.ts

@@ -1,3 +1,3 @@
 import SearchBox from './components/Search.vue'
-import {useSearchIndex} from './composables/index.js'
-export {SearchBox, useSearchIndex}
+import {loadSearchIndexJSON, useSearchIndex} from './composables/index.js'
+export {SearchBox, loadSearchIndexJSON, useSearchIndex}

package/dist/client/index.js

@@ -1,4 +1,4 @@
 import SearchBox from './components/Search.vue'
-import {useSearchIndex} from './composables/index.js'
+import {loadSearchIndexJSON, useSearchIndex} from './composables/index.js'
 
-export {SearchBox, useSearchIndex}
+export {SearchBox, loadSearchIndexJSON, useSearchIndex}

package/dist/client/shim.d.ts

@@ -6,7 +6,9 @@ declare module '*.vue' {
 }
 
 declare module '@internal/minisearchIndex' {
-  const searchIndex: Record<string, () => Promise<{ default: string }>>
+  import type { SearchIndexData } from './composables/searchIndex.js'
+
+  const searchIndex: SearchIndexData
   export {
     searchIndex,
   }

package/dist/node/index.d.ts

@@ -1,4 +1,5 @@
 import {SearchOptions, SearchPluginOptions} from '../shared/index.js'
+import 'minisearch'
 import {App, Plugin} from 'vuepress/core'
 export * from '../shared/index.js'
 /**

package/dist/node/index.js

@@ -1,3 +1,4 @@
+import {createTokenizer} from '../shared/index.js'
 import MiniSearch from 'minisearch'
 import pMap from 'p-map'
 import sanitizeHTML from 'sanitize-html'
@@ -7,20 +8,23 @@ export * from '../shared/index.js'
 
 const SEARCH_INDEX_DIR = 'internal/minisearchIndex/'
 
-const indexByLocales = new Map()
+const MAX_SEARCHABLE_TEXT_LENGTH = 8e3
 
-const indexCache = new Map()
+const SEARCH_INDEX_SHARD_SIZE = 5e4
+
+const indexByLocales = /* @__PURE__ */ new Map()
+
+const indexCache = /* @__PURE__ */ new Map()
+
+const writtenIndexFingerprints = /* @__PURE__ */ new Map()
 
 function getIndexByLocale(locale, lang, options) {
   let index = indexByLocales.get(locale)
   if (!index) {
-    const segmenter = new Intl.Segmenter(lang, {granularity: 'word'})
     index = new MiniSearch({
       fields: ['title', 'titles', 'text'],
       storeFields: ['title', 'titles'],
-      tokenize(text) {
-        return Array.from(segmenter.segment(text)).map((s) => s.segment)
-      },
+      tokenize: createTokenizer(lang),
       ...options.miniSearch?.options,
     })
     indexByLocales.set(locale, index)
@@ -45,6 +49,7 @@ async function prepareSearchIndex({app, isSearchable, searchOptions}) {
   const start = performance.now()
   indexByLocales.clear()
   indexCache.clear()
+  writtenIndexFingerprints.clear()
   await pMap(app.pages, (p) => indexFile(p, searchOptions, isSearchable), {concurrency: 64})
   await writeTemp(app)
   if (app.env.isBuild) {
@@ -56,27 +61,103 @@ async function prepareSearchIndex({app, isSearchable, searchOptions}) {
       `\n[${colors.green('@vuepress-plume/plugin-search')}] prepare search time spent: ${(performance.now() - start).toFixed(2)}ms`,
     )
 }
-Promise.resolve()
+
+let indexTaskQueue = Promise.resolve()
+function runExclusive(task) {
+  const result = indexTaskQueue.then(task)
+  indexTaskQueue = result.then(
+    () => {},
+    () => {},
+  )
+  return result
+}
+
+function prepareSearchIndexInBackground(options) {
+  runExclusive(() => prepareSearchIndex(options)).catch((error) => {
+    logger.error(
+      `${colors.green('[@vuepress-plume/plugin-search]')} failed to prepare search index:`,
+      error,
+    )
+  })
+}
+
+async function onSearchIndexUpdated(app, {page, isSearchable, searchOptions}) {
+  if (isSearchable && !isSearchable(page)) return
+  await runExclusive(async () => {
+    await indexFile(page, searchOptions, isSearchable)
+    await writeTemp(app)
+  })
+}
+
+async function onSearchIndexRemoved(app, {page, isSearchable, searchOptions}) {
+  if (isSearchable && !isSearchable(page)) return
+  const cacheKey = page.filePathRelative
+  if (!cacheKey) return
+  await runExclusive(async () => {
+    const index = getIndexByLocale(page.pathLocale, page.lang, searchOptions)
+    const cache = indexCache.get(cacheKey)
+    if (cache?.length) index.removeAll(cache)
+    indexCache.delete(cacheKey)
+    await writeTemp(app)
+  })
+}
+
+function splitSearchIndex(serialized, shardSize = SEARCH_INDEX_SHARD_SIZE) {
+  const {index} = serialized
+  if (shardSize <= 0 || index.length <= shardSize)
+    return {
+      meta: serialized,
+      shards: [],
+    }
+  const shards = []
+  for (let i = 0; i < index.length; i += shardSize) shards.push(index.slice(i, i + shardSize))
+  return {
+    meta: {
+      ...serialized,
+      index: [],
+    },
+    shards,
+  }
+}
+
+function buildIndexFiles(localeName, serialized, shardSize = SEARCH_INDEX_SHARD_SIZE) {
+  const {meta, shards} = splitSearchIndex(serialized, shardSize)
+  const files = {}
+  shards.forEach((entries, i) => {
+    files[`searchBox-${localeName}-${i}.js`] =
+      `export default ${JSON.stringify(JSON.stringify(entries))}`
+  })
+  const shardImports = shards.length
+    ? `\nexport const shards = [${shards.map((_, i) => `() => import('@${SEARCH_INDEX_DIR}searchBox-${localeName}-${i}.js')`).join(', ')}]`
+    : ''
+  files[`searchBox-${localeName}.js`] =
+    `export default ${JSON.stringify(JSON.stringify(meta))}${shardImports}`
+  return files
+}
 
 async function writeTemp(app) {
   const records = []
   const promises = []
-  for (const [locale] of indexByLocales) {
-    const index = indexByLocales.get(locale)
-    const filename = `searchBox-${locale.replace(/^\/|\/$/g, '').replace(/\//g, '_') || 'default'}.js`
-    records.push(`${JSON.stringify(locale)}: () => import('@${SEARCH_INDEX_DIR}${filename}')`)
+  const writeIfChanged = (filename, content) => {
+    const filePath = `${SEARCH_INDEX_DIR}${filename}`
+    if (writtenIndexFingerprints.get(filePath) === content) return
     promises.push(
-      app.writeTemp(
-        `${SEARCH_INDEX_DIR}${filename}`,
-        `export default ${JSON.stringify(JSON.stringify(index) ?? {})}`,
-      ),
+      app.writeTemp(filePath, content).then(() => {
+        writtenIndexFingerprints.set(filePath, content)
+      }),
+    )
+  }
+  for (const [locale, localeIndex] of indexByLocales) {
+    const localeName = locale.replace(/^\/|\/$/g, '').replace(/\//g, '_') || 'default'
+    records.push(
+      `${JSON.stringify(locale)}: () => import('@${SEARCH_INDEX_DIR}searchBox-${localeName}.js')`,
     )
+    const files = buildIndexFiles(localeName, localeIndex.toJSON())
+    for (const [filename, content] of Object.entries(files)) writeIfChanged(filename, content)
   }
-  promises.push(
-    app.writeTemp(
-      `${SEARCH_INDEX_DIR}index.js`,
-      `export const searchIndex = {${records.join(',')}}${app.env.isDev ? `\n${genHmrCode('searchIndex')}` : ''}`,
-    ),
+  writeIfChanged(
+    'index.js',
+    `export const searchIndex = {${records.join(',')}}${app.env.isDev ? `\n${genHmrCode('searchIndex')}` : ''}`,
   )
   await Promise.all(promises)
 }
@@ -85,45 +166,52 @@ async function indexFile(page, options, isSearchable) {
   if (!page.filePath || page.frontmatter?.search === false) return
   if (isSearchable && !isSearchable(page)) return
   const fileId = page.path
-  const locale = page.pathLocale
-  const lang = page.lang
-  const index = getIndexByLocale(locale, lang, options)
-  const cache = getIndexCache(fileId)
-  const sections =
-    splitPageIntoSections(`<h1><a href="#"><span>${page.frontmatter.title || page.title}</span></a></h1>
-${page.contentRendered}`)
+  const index = getIndexByLocale(page.pathLocale, page.lang, options)
+  const cache = getIndexCache(page.filePathRelative ?? fileId)
   try {
-    if (cache && cache.length) index.removeAll(cache)
-  } catch {}
-  for await (const section of sections) {
-    if (!section || !(section.text || section.titles)) break
-    const {anchor, text, titles} = section
-    const id = anchor ? [fileId, anchor].join('#') : fileId
-    if (index.has(id)) {
-      if (anchor)
+    if (cache.length) index.removeAll(cache)
+  } catch (error) {
+    logger.error(
+      `${colors.green('[@vuepress-plume/plugin-search]')} failed to remove stale index entries:`,
+      error,
+    )
+  }
+  cache.length = 0
+  for (const item of createPageSectionItems(page))
+    if (index.has(item.id)) {
+      if (item.id !== fileId)
         logger.error(
-          `${colors.green('[@vuepress-plume/plugin-search]')} duplicate heading anchor : ${colors.cyan(titles.join(' >> '))} \n at ${colors.cyan(fileId)}`,
+          `${colors.green('[@vuepress-plume/plugin-search]')} duplicate heading anchor : ${colors.cyan([...item.titles, item.title].join(' >> '))} \n at ${colors.cyan(fileId)}`,
         )
       else
         logger.error(
           `${colors.green('[@vuepress-plume/plugin-search]')} duplicate page permalink : ${colors.cyan(fileId)}`,
         )
     } else {
-      const item = {
-        id,
-        text,
-        title: titles.at(-1),
-        titles: titles.slice(0, -1),
-      }
       index.add(item)
       cache.push(item)
     }
+}
+
+function* createPageSectionItems(page) {
+  const html = `<h1><a href="#"><span>${page.frontmatter.title || page.title || page.filePathRelative || ''}</span></a></h1>\n${page.contentRendered}`
+  const fileId = page.path
+  for (const section of splitPageIntoSections(html)) {
+    const {anchor, text, titles} = section
+
+    if (!text && !titles.length) continue
+    yield {
+      id: anchor ? `${fileId}#${anchor}` : fileId,
+      text,
+      title: titles.at(-1),
+      titles: titles.slice(0, -1),
+    }
   }
 }
 
-const headingRegex = /<h(\d*).*?>(<a.*? href="#.*?".*?>[\s\S]*?<\/a>)<\/h\1>/gi
+const headingRegex = /<h(\d)[^>]*>(<a.*? href="#[^"]*"[^>]*>[\s\S]*?<\/a>)<\/h\1>/gi
 
-const headingContentRegex = /<a.*? href="#(.*?)".*?><span>([\s\S]*?)<\/span><\/a>/i
+const headingContentRegex = /<a.*? href="#([^"]*)"[^>]*><span>([\s\S]*?)<\/span><\/a>/i
 
 const ignoreHeadingRegex = /<template[^>]*>[\s\S]*<\/template>/gi
 
@@ -140,7 +228,10 @@ function* splitPageIntoSections(html) {
     const content = result[i + 2]
     if (!title || !content) continue
     if (level === 0) parentTitles = [title]
-    else parentTitles[level] = title
+    else {
+      parentTitles.length = level
+      parentTitles[level] = title
+    }
     let titles = parentTitles.slice(0, level)
     titles[level] = title
     titles = titles.filter(Boolean)
@@ -154,7 +245,9 @@ function* splitPageIntoSections(html) {
 
 function getSearchableText(content) {
   content = clearHtmlTags(content)
-  return content
+  return content.length > MAX_SEARCHABLE_TEXT_LENGTH
+    ? content.slice(0, MAX_SEARCHABLE_TEXT_LENGTH)
+    : content
 }
 
 function clearHtmlTags(str) {
@@ -191,6 +284,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Reset search',
       backButtonTitle: 'Close search',
       noResultsText: 'No results for',
+      searchIndexErrorText: 'Failed to load the search index.',
+      noscriptText: 'Search is unavailable without JavaScript.',
       footer: {
         selectText: 'to select',
         selectKeyAriaLabel: 'enter',
@@ -209,6 +304,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '重置搜索',
       backButtonTitle: '关闭',
       noResultsText: '无搜索结果：',
+      searchIndexErrorText: '搜索索引加载失败。',
+      noscriptText: '未启用 JavaScript，搜索不可用。',
       footer: {
         selectText: '选择',
         selectKeyAriaLabel: '输入',
@@ -227,6 +324,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '重設搜尋',
       backButtonTitle: '關閉',
       noResultsText: '無搜尋結果：',
+      searchIndexErrorText: '搜尋索引載入失敗。',
+      noscriptText: '未啟用 JavaScript，搜尋無法使用。',
       footer: {
         selectText: '選擇',
         selectKeyAriaLabel: '輸入',
@@ -245,6 +344,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Suche zurücksetzen',
       backButtonTitle: 'Schließen',
       noResultsText: 'Keine Suchergebnisse:',
+      searchIndexErrorText: 'Der Suchindex konnte nicht geladen werden.',
+      noscriptText: 'Die Suche ist ohne JavaScript nicht verfügbar.',
       footer: {
         selectText: 'Auswählen',
         selectKeyAriaLabel: 'Eingabe',
@@ -263,6 +364,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Réinitialiser la recherche',
       backButtonTitle: 'Fermer',
       noResultsText: 'Aucun résultat trouvé :',
+      searchIndexErrorText: 'Échec du chargement de l’index de recherche.',
+      noscriptText: 'La recherche est indisponible sans JavaScript.',
       footer: {
         selectText: 'sélectionner',
         selectKeyAriaLabel: 'Entrée',
@@ -281,6 +384,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: 'Сбросить поиск',
       backButtonTitle: 'Закрыть',
       noResultsText: 'Нет результатов поиска:',
+      searchIndexErrorText: 'Не удалось загрузить поисковый индекс.',
+      noscriptText: 'Поиск недоступен без JavaScript.',
       footer: {
         selectText: 'Выбрать',
         selectKeyAriaLabel: 'Ввод',
@@ -299,6 +404,8 @@ const SEARCH_LOCALES = [
       resetButtonTitle: '検索をリセット',
       backButtonTitle: '閉じる',
       noResultsText: '検索結果がありません：',
+      searchIndexErrorText: '検索インデックスの読み込みに失敗しました。',
+      noscriptText: 'JavaScript が無効のため、検索を利用できません。',
       footer: {
         selectText: '選択',
         selectKeyAriaLabel: '入力',
@@ -343,13 +450,39 @@ function searchPlugin({locales = {}, isSearchable, ...searchOptions} = {}) {
         })
       else {
         await prepareSearchIndexPlaceholder(app)
-        prepareSearchIndex({
+        prepareSearchIndexInBackground({
           app,
           isSearchable,
           searchOptions,
         })
       }
     },
+    onPageUpdated: async (app, type, pageNew, pageOld) => {
+      if (type === 'delete') {
+        if (pageOld?.filePathRelative)
+          await onSearchIndexRemoved(app, {
+            page: pageOld,
+            isSearchable,
+            searchOptions,
+          })
+        return
+      }
+      const becameUnsearchable = !!isSearchable && !!pageNew && !isSearchable(pageNew)
+      const page = becameUnsearchable ? pageOld : pageNew
+      if (!page?.filePathRelative) return
+      if (becameUnsearchable)
+        await onSearchIndexRemoved(app, {
+          page,
+          isSearchable,
+          searchOptions,
+        })
+      else
+        await onSearchIndexUpdated(app, {
+          page,
+          isSearchable,
+          searchOptions,
+        })
+    },
   })
 }
 

package/dist/shared/index.d.ts

@@ -16,6 +16,25 @@ export interface SearchLocaleOptions {
   backButtonTitle: string
   /** Text shown when no results found / 无搜索结果时显示的文本 */
   noResultsText: string
+  /**
+   * Text shown when the search index is missing or fails to load.
+   *
+   * 搜索索引缺失或加载失败时显示的文本。
+   */
+  searchIndexErrorText?: string
+  /**
+   * Fallback text shown when JavaScript is disabled.
+   *
+   * 禁用 JavaScript 时显示的降级提示文本。
+   *
+   * 请注意：该文本会渲染在 `<noscript>` 中，必须为不含 `<`、`>`、`&`、引号等
+   * 需要 HTML 转义的纯文本，否则在启用脚本的浏览器中水合时会与原文不一致。
+   *
+   * Note: this text is rendered inside `<noscript>`, so it must be plain text
+   * without characters requiring HTML escaping (`<`, `>`, `&`, quotes), otherwise
+   * it would mismatch during hydration in browsers with scripting enabled.
+   */
+  noscriptText?: string
   /** Footer keyboard shortcut hints / 底部键盘快捷键提示 */
   footer: {
     /** Text for select action / 选择操作的文本 */
@@ -40,6 +59,28 @@ export interface SearchLocaleOptions {
  * 搜索框的语言配置类型。
  */
 export type SearchBoxLocales = LocaleConfig<SearchLocaleOptions>
+/**
+ * Create a tokenizer shared by the node (index build) and client (query) sides.
+ *
+ * 创建由 Node 端（构建索引）与客户端（查询）共享的分词器。
+ *
+ * MiniSearch requires the tokenizer used to build the index to be identical to
+ * the one used at query time. Defining it in one place guarantees both sides
+ * use the same strategy: `Intl.Segmenter` when available, otherwise the same
+ * deterministic whitespace fallback. Blank and punctuation-only tokens are
+ * discarded on both sides, so they never pollute the index or the query.
+ *
+ * MiniSearch 要求构建索引与查询时使用完全一致的分词器。集中定义可保证两端策略一致：
+ * 支持 `Intl.Segmenter` 时使用它分词，否则统一退化为确定性的空白符分词。
+ * 两端都会丢弃空白与纯标点词元，避免污染索引与查询。
+ *
+ * @param lang - Language code for word segmentation / 用于分词的语言代码
+ * @returns Tokenizer that splits a string into tokens / 将字符串切分为词元的函数
+ * @example
+ * const tokenize = createTokenizer('en')
+ * tokenize('Hello world') // ['Hello', 'world'] with Intl.Segmenter
+ */
+export declare function createTokenizer(lang: string): (text: string) => string[]
 /**
  * Options for the search plugin.
  *

package/dist/shared/index.js

@@ -1 +1,16 @@
-export {}
+function isWordToken(token) {
+  return /\p{L}|\p{N}/u.test(token)
+}
+
+function createTokenizer(lang) {
+  if (typeof Intl !== 'undefined' && typeof Intl.Segmenter === 'function') {
+    const segmenter = new Intl.Segmenter(lang, {granularity: 'word'})
+    return (text) =>
+      Array.from(segmenter.segment(text))
+        .map((segment) => segment.segment)
+        .filter(isWordToken)
+  }
+  return (text) => text.split(/\s+/).filter(isWordToken)
+}
+
+export {createTokenizer}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vuepress-plume/plugin-search",
   "type": "module",
-  "version": "1.0.0-rc.211",
+  "version": "1.0.0-rc.213",
   "description": "The Plugin for VuePress 2 - local search",
   "author": "pengzhanbo <volodymyr@foxmail.com>",
   "license": "MIT",
@@ -14,6 +14,12 @@
   "bugs": {
     "url": "https://github.com/pengzhanbo/vuepress-theme-plume/issues"
   },
+  "keywords": [
+    "VuePress",
+    "vuepress plugin",
+    "mini search",
+    "vuepress-plugin-search"
+  ],
   "exports": {
     ".": {
       "types": "./dist/node/index.d.ts",
@@ -34,27 +40,21 @@
     "vuepress": "2.0.0-rc.31"
   },
   "dependencies": {
-    "@vuepress/helper": "2.0.0-rc.134",
-    "@vueuse/core": "^14.4.0",
-    "@vueuse/integrations": "^14.4.0",
+    "@vuepress/helper": "2.0.0-rc.135",
+    "@vueuse/core": "^15.0.0",
+    "@vueuse/integrations": "^15.0.0",
     "chokidar": "5.0.0",
     "focus-trap": "^8.2.2",
     "mark.js": "^8.11.1",
     "minisearch": "^7.2.0",
     "p-map": "^7.0.8",
-    "sanitize-html": "^2.17.7",
-    "vue": "^3.5.42"
+    "sanitize-html": "^2.18.0",
+    "vue": "^3.5.43"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
-  "keyword": [
-    "VuePress",
-    "vuepress plugin",
-    "mini search",
-    "vuepress-plugin-search"
-  ],
   "scripts": {
     "build": "pnpm run tsdown && pnpm run copy",
     "clean": "rimraf --glob ./dist",

package/dist/client/utils/index.d.ts

@@ -1,84 +0,0 @@
-/**
- * LRU (Least Recently Used) Cache Implementation
- *
- * LRU（最近最少使用）缓存实现
- *
- * Adapted from https://stackoverflow.com/a/46432113/11613622
- *
- * @module plugin-search/client/utils/lru
- */
-/**
- * Generic LRU Cache implementation using Map.
- *
- * 使用 Map 实现的通用 LRU 缓存。
- *
- * Automatically evicts the least recently used item when the cache reaches
- * its maximum size.
- *
- * 当缓存达到最大容量时，自动淘汰最近最少使用的项。
- *
- * @template K - Key type / 键类型
- * @template V - Value type / 值类型
- * @example
- * const cache = new LRUCache<string, number>(3)
- * cache.set('a', 1)
- * cache.set('b', 2)
- * cache.set('c', 3)
- * cache.set('d', 4) // 'a' is evicted
- * cache.get('b') // returns 2, 'b' becomes most recent
- */
-export declare class LRUCache<K, V> {
-  /** Maximum number of items in the cache / 缓存中的最大项数 */
-  private max
-  /** Internal Map storage / 内部 Map 存储 */
-  private cache
-  /**
-   * Create a new LRU Cache instance.
-   *
-   * 创建新的 LRU 缓存实例。
-   *
-   * @param max - Maximum cache size (default: 10) / 最大缓存大小（默认：10）
-   */
-  constructor(max?: number)
-  /**
-   * Get a value from the cache.
-   *
-   * 从缓存中获取值。
-   *
-   * Accessing an item moves it to the end (most recently used position).
-   *
-   * 访问项会将其移动到末尾（最近使用的位置）。
-   *
-   * @param key - Cache key / 缓存键
-   * @returns Cached value or undefined if not found / 缓存值，未找到则返回 undefined
-   */
-  get(key: K): V | undefined
-  /**
-   * Set a value in the cache.
-   *
-   * 在缓存中设置值。
-   *
-   * If the key already exists, it is moved to the end. If the cache is full,
-   * the oldest item is evicted.
-   *
-   * 如果键已存在，则将其移动到末尾。如果缓存已满，则淘汰最旧的项。
-   *
-   * @param key - Cache key / 缓存键
-   * @param val - Value to cache / 要缓存的值
-   */
-  set(key: K, val: V): void
-  /**
-   * Get the first (oldest) key in the cache.
-   *
-   * 获取缓存中的第一个（最旧的）键。
-   *
-   * @returns The oldest key or undefined if cache is empty / 最旧的键，缓存为空则返回 undefined
-   */
-  first(): K | undefined
-  /**
-   * Clear all items from the cache.
-   *
-   * 清空缓存中的所有项。
-   */
-  clear(): void
-}

package/dist/client/utils/index.js

@@ -1,35 +0,0 @@
-var LRUCache = class {
-  max
-
-  cache
-
-  constructor(max = 10) {
-    this.max = max
-    this.cache = new Map()
-  }
-
-  get(key) {
-    const item = this.cache.get(key)
-    if (item !== void 0) {
-      this.cache.delete(key)
-      this.cache.set(key, item)
-    }
-    return item
-  }
-
-  set(key, val) {
-    if (this.cache.has(key)) this.cache.delete(key)
-    else if (this.cache.size === this.max) this.cache.delete(this.first())
-    this.cache.set(key, val)
-  }
-
-  first() {
-    return this.cache.keys().next().value
-  }
-
-  clear() {
-    this.cache.clear()
-  }
-}
-
-export {LRUCache}