refactor(plugin-webmcp): stabilize runtime lifecycle

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ScriptedAlchemy

e2e/fixtures/plugin-webmcp/index.test.ts

@@ -346,10 +346,7 @@ test.describe('plugin-webmcp development server', () => {
 
     await expect
       .poll(async () => {
-        const tool = (await listTools(page)).find(
-          candidate => candidate.name === 'fixture_increment_counter',
-        );
-        return tool?.description;
+        return (await findTool(page, 'fixture_increment_counter'))?.description;
       })
       .toContain('by one');
     await executeTool(page, 'fixture_reset_counter', {});
@@ -382,10 +379,7 @@ test.describe('plugin-webmcp development server', () => {
 
     await expect
       .poll(async () => {
-        const tool = (await listTools(page)).find(
-          candidate => candidate.name === 'fixture_page_scoped',
-        );
-        return tool?.description;
+        return (await findTool(page, 'fixture_page_scoped'))?.description;
       })
       .toContain('guide page');
 

e2e/fixtures/plugin-webmcp/webmcpTestUtils.ts

@@ -6,11 +6,9 @@ export interface TestingTool {
   inputSchema?: string;
 }
 
-type ModelContextTool = TestingTool;
-
 interface ProducerModelContext {
-  getTools(): Promise<ModelContextTool[]>;
-  executeTool(tool: ModelContextTool, input: string): Promise<string | null>;
+  getTools(): Promise<TestingTool[]>;
+  executeTool(tool: TestingTool, input: string): Promise<string | null>;
 }
 
 interface TestingModelContext {

package.json

@@ -14,8 +14,9 @@
     "lint": "rslint --type-check && prettier . --check && pnpm run check-spell",
     "prepare": "skills-package-manager install && pnpm run build && simple-git-hooks",
     "preview:website": "cd website && npm run preview",
-    "test": "pnpm test:unit && pnpm test:e2e",
+    "test": "pnpm test:type && pnpm test:unit && pnpm test:e2e",
     "test:e2e": "playwright test",
+    "test:type": "pnpm --recursive --if-present run test:type",
     "test:unit": "rstest run",
     "update:rsbuild": "npx taze minor --include /rsbuild/ -w -r -l"
   },

packages/core/src/node/runtimeModule/pageData/rsbuildPlugin.ts

@@ -1,5 +1,4 @@
 import type { RsbuildPlugin } from '@rsbuild/core';
-import type { PageData } from '@rspress/shared';
 import { logger } from '@rspress/shared/logger';
 import { pluginVirtualModule } from 'rsbuild-plugin-virtual-module';
 import { type FactoryContext, RuntimeModuleID } from '../types';
@@ -11,17 +10,7 @@ export const rsbuildPluginDocVM = async ({
   routeService,
   pluginDriver,
 }: Omit<FactoryContext, 'alias'>): Promise<RsbuildPlugin[]> => {
-  const ref: {
-    pageData: PageData | null;
-    searchIndex: Record<string, string> | null;
-    indexHashByGroup: Record<string, string> | null;
-    filepaths: string[];
-  } = {
-    pageData: null,
-    searchIndex: null,
-    indexHashByGroup: null,
-    filepaths: [],
-  };
+  let pageDataResult: Awaited<ReturnType<typeof createPageData>> | undefined;
   let webAlias: Record<string, string> | undefined;
   let refreshPromise: Promise<void> | undefined;
 
@@ -31,20 +20,14 @@ export const rsbuildPluginDocVM = async ({
     }
     refreshPromise ??= (async () => {
       const now = performance.now();
-      const { pageData, indexHashByGroup, searchIndex, filepaths } =
-        await createPageData({
-          config,
-          alias: webAlias,
-          userDocRoot,
-          routeService,
-          pluginDriver,
-        });
+      pageDataResult = await createPageData({
+        config,
+        alias: webAlias,
+        userDocRoot,
+        routeService,
+        pluginDriver,
+      });
       logger.debug(`createPageData cost: ${performance.now() - now}ms`);
-
-      ref.pageData = pageData;
-      ref.searchIndex = searchIndex;
-      ref.indexHashByGroup = indexHashByGroup;
-      ref.filepaths = filepaths;
     })();
     try {
       await refreshPromise;
@@ -65,11 +48,11 @@ export const rsbuildPluginDocVM = async ({
         api.processAssets(
           { stage: 'report', environments: ['web'] },
           ({ compilation, compiler }) => {
-            if (!ref.searchIndex) {
+            if (!pageDataResult) {
               return;
             }
             for (const [filename, stringifiedIndex] of Object.entries(
-              ref.searchIndex,
+              pageDataResult.searchIndex,
             )) {
               compilation.emitAsset(
                 `static/${filename}`,
@@ -89,12 +72,12 @@ export const rsbuildPluginDocVM = async ({
       virtualModules: {
         [RuntimeModuleID.PageData]: async ({ addDependency }) => {
           await refreshPageData();
-          for (const file of ref.filepaths) {
+          for (const file of pageDataResult?.filepaths ?? []) {
             addDependency(file);
           }
 
-          return `export const pageData = ${JSON.stringify(ref.pageData, null, 2)};
-          export const searchIndexHash = ${JSON.stringify(ref.indexHashByGroup, null, 2)};`;
+          return `export const pageData = ${JSON.stringify(pageDataResult?.pageData ?? null, null, 2)};
+          export const searchIndexHash = ${JSON.stringify(pageDataResult?.indexHashByGroup ?? null, null, 2)};`;
         },
       },
     }),

packages/core/src/node/runtimeModule/siteData/createSiteData.test.ts

@@ -0,0 +1,35 @@
+import type { UserConfig } from '@rspress/shared';
+import { describe, expect, test } from '@rstest/core';
+import { createSiteData } from './createSiteData';
+
+describe('createSiteData', () => {
+  test('preserves the default local search configuration', async () => {
+    const { siteData } = await createSiteData({});
+
+    expect(siteData.search).toEqual({
+      mode: 'local',
+      searchHooks: undefined,
+    });
+  });
+
+  test('preserves disabled search in runtime site data', async () => {
+    const { siteData } = await createSiteData({ search: false });
+
+    expect(siteData.search).toBe(false);
+  });
+
+  test('removes search hooks without mutating user config', async () => {
+    const search = {
+      mode: 'local',
+      searchHooks: '/absolute/search-hooks.ts',
+    } satisfies NonNullable<UserConfig['search']>;
+
+    const { siteData } = await createSiteData({ search });
+
+    expect(siteData.search).toEqual({
+      mode: 'local',
+      searchHooks: undefined,
+    });
+    expect(search.searchHooks).toBe('/absolute/search-hooks.ts');
+  });
+});

packages/core/src/node/runtimeModule/siteData/createSiteData.ts

@@ -5,13 +5,15 @@ import { normalizeThemeConfig } from './normalizeThemeConfig';
 export async function createSiteData(userConfig: UserConfig): Promise<{
   siteData: Omit<SiteData, 'root' | 'pages'>;
 }> {
-  // prevent modify the origin config object
-  const tempSearchObj = Object.assign({}, userConfig.search);
-
-  // searchHooks is a absolute path which may leak information
-  if (tempSearchObj) {
-    tempSearchObj.searchHooks = undefined;
-  }
+  const search =
+    userConfig.search === false
+      ? false
+      : {
+          mode: 'local' as const,
+          ...userConfig.search,
+          // searchHooks is an absolute path which may leak information
+          searchHooks: undefined,
+        };
 
   const siteData: Omit<SiteData, 'root' | 'pages'> = {
     base: userConfig.base ?? '/',
@@ -33,7 +35,7 @@ export async function createSiteData(userConfig: UserConfig): Promise<{
       default: userConfig?.multiVersion?.default || '',
       versions: userConfig?.multiVersion?.versions || [],
     },
-    search: tempSearchObj ?? { mode: 'local' },
+    search,
     markdown: {
       showLineNumbers: userConfig?.markdown?.showLineNumbers ?? false,
       defaultWrapCode: userConfig?.markdown?.defaultWrapCode ?? false,

packages/core/src/theme/logic/useFullTextSearch.ts

@@ -1,38 +1,59 @@
 import { usePageData } from '@rspress/core/runtime';
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import { PageSearcher } from '../components/Search/logic/search';
 import type { MatchResult } from '../components/Search/logic/types';
 
-export function useFullTextSearch(): {
-  initialized: boolean;
-  search: (keyword: string, limit?: number) => Promise<MatchResult>;
-} {
+type Search = (keyword: string, limit?: number) => Promise<MatchResult>;
+
+type FullTextSearchState =
+  | { initialized: false; search: undefined }
+  | { initialized: true; search: Search };
+
+export function useFullTextSearch(): FullTextSearchState {
   const { siteData, page } = usePageData();
-  const [initialized, setInitialized] = useState(false);
-  const searchRef = useRef<PageSearcher | null>(null);
+  const searchOptions = siteData.search;
+  const versionedSearch =
+    typeof searchOptions !== 'boolean' && (searchOptions.versioned ?? true);
+  const currentVersion = versionedSearch ? page.version : '';
+  const searcher = useMemo(
+    () =>
+      searchOptions === false
+        ? null
+        : new PageSearcher({
+            ...searchOptions,
+            mode: 'local',
+            currentLang: page.lang,
+            currentVersion,
+          }),
+    [searchOptions, page.lang, currentVersion],
+  );
+  const [initializedSearcher, setInitializedSearcher] =
+    useState<PageSearcher | null>(null);
 
   useEffect(() => {
-    async function init() {
-      if (!initialized) {
-        const searcher = new PageSearcher({
-          ...siteData.search,
-          mode: 'local',
-          currentLang: page.lang,
-          currentVersion: page.version,
-        });
-        searchRef.current = searcher;
-        await searcher.init();
-        setInitialized(true);
-      }
+    setInitializedSearcher(null);
+    if (!searcher) {
+      return;
     }
-    init();
-  }, []);
+
+    let active = true;
+    void searcher.init().then(() => {
+      if (active) {
+        setInitializedSearcher(searcher);
+      }
+    });
+
+    return () => {
+      active = false;
+    };
+  }, [searcher]);
+
+  if (initializedSearcher !== searcher || !searcher) {
+    return { initialized: false, search: undefined };
+  }
 
   return {
-    initialized,
-    search: searchRef.current?.match.bind(searchRef.current) as (
-      keyword: string,
-      limit?: number,
-    ) => Promise<MatchResult>,
+    initialized: true,
+    search: searcher.match.bind(searcher),
   };
 }

packages/plugin-webmcp/package.json

@@ -30,7 +30,8 @@
   "scripts": {
     "build": "rslib build",
     "dev": "rslib build -w",
-    "reset": "rimraf ./**/node_modules"
+    "reset": "rimraf ./**/node_modules",
+    "test:type": "tsc -p tests/tsconfig.json"
   },
   "devDependencies": {
     "@mcp-b/webmcp-types": "4.0.0",

packages/plugin-webmcp/src/index.ts

@@ -9,36 +9,31 @@ import {
 export type { PluginWebMcpOptions, PluginWebMcpToolsOptions } from './options';
 
 export function pluginWebMcp(options?: PluginWebMcpOptions): RspressPlugin {
-  const normalizedOptions = normalizePluginWebMcpOptions(options);
-  const runtimeOptions: WebMcpRuntimeOptions = {
-    ...normalizedOptions,
-    currentPageEnabled: normalizedOptions.tools.currentPage,
-    searchEnabled: normalizedOptions.tools.search,
-  };
+  const runtimeOptions: WebMcpRuntimeOptions =
+    normalizePluginWebMcpOptions(options);
 
-  const syncRuntimeOptions = (config: UserConfig, isProd: boolean) => {
-    const currentPageEnabled = normalizedOptions.tools.currentPage && isProd;
-    runtimeOptions.currentPageEnabled = currentPageEnabled;
-    runtimeOptions.searchEnabled =
-      normalizedOptions.tools.search && config.search !== false;
-    if (currentPageEnabled && config.llms === false) {
+  const requireSsgMd = (config: UserConfig, isProd: boolean) => {
+    if (!runtimeOptions.tools.currentPage || !isProd) {
+      return false;
+    }
+    if (config.llms === false) {
       throw new Error(
         '[@rspress/plugin-webmcp] The rspress_get_current_page tool requires SSG-MD. Remove `llms: false`, enable `llms`, or disable the current-page WebMCP tool.',
       );
     }
-    return currentPageEnabled;
+    return true;
   };
 
   return {
     name: '@rspress/plugin-webmcp',
     config(config, _configUtils, isProd) {
-      if (syncRuntimeOptions(config, isProd)) {
+      if (requireSsgMd(config, isProd)) {
         config.llms ??= true;
       }
       return config;
     },
     beforeBuild(config, isProd) {
-      syncRuntimeOptions(config, isProd);
+      requireSsgMd(config, isProd);
     },
     globalUIComponents: [
       [path.join(__dirname, 'runtime/WebMcpRuntime.js'), runtimeOptions],

packages/plugin-webmcp/src/options.ts

@@ -15,10 +15,7 @@ export interface NormalizedPluginWebMcpOptions {
   tools: Required<PluginWebMcpToolsOptions>;
 }
 
-export interface WebMcpRuntimeOptions extends NormalizedPluginWebMcpOptions {
-  currentPageEnabled: boolean;
-  searchEnabled: boolean;
-}
+export type WebMcpRuntimeOptions = NormalizedPluginWebMcpOptions;
 
 export function normalizePluginWebMcpOptions(
   options: PluginWebMcpOptions = {},