@xiaou66/vite-plugin-vue-mcp-next 1.2.0 → 1.3.1

package/dist/index.js

@@ -51,7 +51,8 @@ var MCP_TOOL_NAMES = {
   highlightComponent: "highlight_component",
   getRouterInfo: "get_router_info",
   getPiniaTree: "get_pinia_tree",
-  getPiniaState: "get_pinia_state"
+  getPiniaState: "get_pinia_state",
+  getElementContext: "get_element_context"
 };
 var VIRTUAL_RUNTIME_ID = "virtual:vite-plugin-vue-mcp-next/runtime";
 var RESOLVED_VIRTUAL_RUNTIME_ID = `\0${VIRTUAL_RUNTIME_ID}`;
@@ -62,6 +63,12 @@ var RESOLVED_VIRTUAL_SNAPDOM_LOADER_ID = `\0${VIRTUAL_SNAPDOM_LOADER_ID}`;
 var DEFAULT_MCP_CLIENT_SERVER_NAME = "vite-mcp-next";
 var LEGACY_MCP_CLIENT_SERVER_NAMES = ["vue-mcp-next"];
 var RUNTIME_PAGE_RECONNECTED_EVENT = "vite-plugin-vue-mcp-next:page-reconnected";
+var RUNTIME_PAGE_CONNECTED_EVENT = "vite-plugin-vue-mcp-next:page-connected";
+var RUNTIME_PAGE_DISCONNECTED_EVENT = "vite-plugin-vue-mcp-next:page-disconnected";
+var RUNTIME_PAGE_HEARTBEAT_EVENT = "vite-plugin-vue-mcp-next:heartbeat";
+var DEFAULT_RUNTIME_PAGE_HEARTBEAT_TIMEOUT_MS = 45e3;
+var DEFAULT_RUNTIME_PAGE_HEARTBEAT_SCAN_INTERVAL_MS = 45e3;
+var DEFAULT_ELEMENT_PICKER_TOAST_DURATION_MS = 2200;
 var DEFAULT_OPTIONS = {
   mcpPath: DEFAULT_MCP_PATH,
   host: "localhost",
@@ -80,6 +87,16 @@ var DEFAULT_OPTIONS = {
   skill: {
     autoConfig: true
   },
+  elementPicker: {
+    enabled: true,
+    shortcut: {
+      altKey: true,
+      shiftKey: true,
+      metaKey: false,
+      ctrlKey: false
+    },
+    toastDurationMs: DEFAULT_ELEMENT_PICKER_TOAST_DURATION_MS
+  },
   runtime: {
     mode: "auto",
     evaluate: {
@@ -154,6 +171,14 @@ function mergeOptions(options = {}) {
       ...DEFAULT_OPTIONS.skill,
       ...options.skill
     },
+    elementPicker: {
+      ...DEFAULT_OPTIONS.elementPicker,
+      ...options.elementPicker,
+      shortcut: {
+        ...DEFAULT_OPTIONS.elementPicker.shortcut,
+        ...options.elementPicker?.shortcut
+      }
+    },
     runtime: {
       ...DEFAULT_OPTIONS.runtime,
       ...options.runtime,
@@ -574,9 +599,164 @@ function registerDomTools(server, ctx) {
   );
 }
 
-// src/mcp/tools/evaluate.ts
+// src/mcp/tools/elementContext.ts
 import { z as z3 } from "zod";
 
+// src/shared/elementId.ts
+var PROJECT_SOURCE_ID_PATTERN = /^(.+\.(?:vue|tsx|jsx|ts|js)):(\d+):(\d+)$/;
+var RUNTIME_ID_PATTERN = /^runtime:([A-Za-z0-9_-]+)$/;
+var PACKAGE_ID_PREFIX = "pkg:";
+function parseElementId(elementId) {
+  const sourceMatch = PROJECT_SOURCE_ID_PATTERN.exec(elementId);
+  if (sourceMatch) {
+    return {
+      kind: "project-source",
+      elementId,
+      file: sourceMatch[1],
+      line: Number(sourceMatch[2]),
+      column: Number(sourceMatch[3])
+    };
+  }
+  if (elementId.startsWith(PACKAGE_ID_PREFIX)) {
+    return parsePackageElementId(elementId);
+  }
+  const runtimeMatch = RUNTIME_ID_PATTERN.exec(elementId);
+  if (runtimeMatch) {
+    return {
+      kind: "runtime",
+      elementId,
+      runtimeId: runtimeMatch[1]
+    };
+  }
+  return {
+    kind: "invalid",
+    elementId,
+    reason: "unsupported elementId format"
+  };
+}
+function parsePackageElementId(elementId) {
+  const value = elementId.slice(PACKAGE_ID_PREFIX.length);
+  const parts = value.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    return {
+      kind: "invalid",
+      elementId,
+      reason: "package elementId must include packageName and entryFile"
+    };
+  }
+  const scoped = parts[0]?.startsWith("@");
+  const packageName = scoped ? parts.slice(0, 2).join("/") : parts[0];
+  const entryFile = parts.slice(scoped ? 2 : 1).join("/");
+  if (!entryFile) {
+    return {
+      kind: "invalid",
+      elementId,
+      reason: "package elementId must include entryFile"
+    };
+  }
+  return {
+    kind: "package",
+    elementId,
+    packageName,
+    entryFile
+  };
+}
+
+// src/mcp/tools/elementContext.ts
+function registerElementContextTools(server, ctx) {
+  server.registerTool(
+    MCP_TOOL_NAMES.getElementContext,
+    {
+      description: "Get editable source, Vue component, and DOM context for a copied elementId.",
+      inputSchema: {
+        elementId: z3.string(),
+        pageId: z3.string().optional()
+      }
+    },
+    async (input) => {
+      const runtimeResult = await tryRuntimeElementContext(
+        ctx,
+        input.elementId,
+        input.pageId
+      );
+      if (runtimeResult) {
+        return createToolResponse(runtimeResult);
+      }
+      return createToolResponse(createStaticElementContext(input.elementId));
+    }
+  );
+}
+async function tryRuntimeElementContext(ctx, elementId, pageId) {
+  if (!ctx.rpcServer) {
+    return parseElementId(elementId).kind === "runtime" ? createRuntimeUnavailableContext(elementId) : void 0;
+  }
+  try {
+    resolvePageTarget(ctx, pageId);
+  } catch (error) {
+    const parsed = parseElementId(elementId);
+    if (parsed.kind === "project-source" || parsed.kind === "package") {
+      return void 0;
+    }
+    return {
+      ok: false,
+      elementId,
+      error: error instanceof Error ? error.message : String(error),
+      limitations: ["call list_pages and pass pageId when multiple pages exist"]
+    };
+  }
+  return await requestRuntimeData(ctx, (event) => {
+    void ctx.rpcServer?.getElementContext({ event, elementId });
+  });
+}
+function createStaticElementContext(elementId) {
+  const parsed = parseElementId(elementId);
+  if (parsed.kind === "project-source") {
+    return {
+      ok: true,
+      elementId,
+      editable: true,
+      codeLocation: {
+        file: parsed.file,
+        line: parsed.line,
+        column: parsed.column
+      },
+      limitations: ["runtime unavailable, DOM and component context omitted"]
+    };
+  }
+  if (parsed.kind === "package") {
+    return {
+      ok: true,
+      elementId,
+      editable: false,
+      packageLocation: {
+        packageName: parsed.packageName,
+        entryFile: parsed.entryFile
+      },
+      limitations: ["third-party package source is not editable from this project"]
+    };
+  }
+  if (parsed.kind === "runtime") {
+    return createRuntimeUnavailableContext(elementId);
+  }
+  return {
+    ok: false,
+    elementId,
+    error: parsed.reason,
+    limitations: ["please provide a copied elementId from the element picker"]
+  };
+}
+function createRuntimeUnavailableContext(elementId) {
+  return {
+    ok: false,
+    elementId,
+    error: "runtime bridge is not connected",
+    limitations: ["runtime ids are only valid while the page is connected"]
+  };
+}
+
+// src/mcp/tools/evaluate.ts
+import { z as z4 } from "zod";
+
 // src/cdp/cdpEvaluate.ts
 async function cdpEvaluate(options) {
   const result = await options.client.Runtime.evaluate({
@@ -597,9 +777,9 @@ function registerEvaluateTools(server, ctx) {
     {
       description: "Evaluate a script in the selected page when explicitly enabled.",
       inputSchema: {
-        pageId: z3.string().optional(),
-        expression: z3.string(),
-        awaitPromise: z3.boolean().optional()
+        pageId: z4.string().optional(),
+        expression: z4.string(),
+        awaitPromise: z4.boolean().optional()
       }
     },
     async (input) => {
@@ -648,18 +828,18 @@ function assertEvaluateEnabled(options) {
 }
 
 // src/mcp/tools/network.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 function registerNetworkTools(server, ctx) {
   server.registerTool(
     MCP_TOOL_NAMES.getNetworkRequests,
     {
       description: "Get captured network request summaries.",
       inputSchema: {
-        pageId: z4.string().optional(),
-        urlContains: z4.string().optional(),
-        method: z4.string().optional(),
-        status: z4.number().optional(),
-        limit: z4.number().optional()
+        pageId: z5.string().optional(),
+        urlContains: z5.string().optional(),
+        method: z5.string().optional(),
+        status: z5.number().optional(),
+        limit: z5.number().optional()
       }
     },
     (input) => {
@@ -682,7 +862,7 @@ function registerNetworkTools(server, ctx) {
     MCP_TOOL_NAMES.getNetworkRequestDetail,
     {
       description: "Get captured network request detail by id.",
-      inputSchema: { id: z4.string() }
+      inputSchema: { id: z5.string() }
     },
     (input) => {
       if (ctx.options.network.mode === "off") {
@@ -699,7 +879,7 @@ function registerNetworkTools(server, ctx) {
     {
       description: "Clear cached network requests.",
       inputSchema: {
-        pageId: z4.string().optional()
+        pageId: z5.string().optional()
       }
     },
     () => {
@@ -710,7 +890,7 @@ function registerNetworkTools(server, ctx) {
 }
 
 // src/mcp/tools/performance.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 
 // src/performance/summary.ts
 function buildPerformanceSummary(input) {
@@ -992,10 +1172,10 @@ function registerPerformanceTools(server, ctx) {
     {
       description: "Record a performance sample for the selected page.",
       inputSchema: {
-        pageId: z5.string().optional(),
-        durationMs: z5.number().optional(),
-        includeMemory: z5.boolean().optional(),
-        includeStacks: z5.boolean().optional()
+        pageId: z6.string().optional(),
+        durationMs: z6.number().optional(),
+        includeMemory: z6.boolean().optional(),
+        includeStacks: z6.boolean().optional()
       }
     },
     async (input) => handleRecordPerformance(ctx, input)
@@ -1005,9 +1185,9 @@ function registerPerformanceTools(server, ctx) {
     {
       description: "Start a performance recording session.",
       inputSchema: {
-        pageId: z5.string().optional(),
-        includeMemory: z5.boolean().optional(),
-        includeStacks: z5.boolean().optional()
+        pageId: z6.string().optional(),
+        includeMemory: z6.boolean().optional(),
+        includeStacks: z6.boolean().optional()
       }
     },
     async (input) => handleStartPerformanceRecording(ctx, input)
@@ -1017,7 +1197,7 @@ function registerPerformanceTools(server, ctx) {
     {
       description: "Stop a performance recording session.",
       inputSchema: {
-        recordingId: z5.string()
+        recordingId: z6.string()
       }
     },
     async (input) => handleStopPerformanceRecording(ctx, input)
@@ -1027,9 +1207,9 @@ function registerPerformanceTools(server, ctx) {
     {
       description: "Get cached performance reports and active sessions.",
       inputSchema: {
-        pageId: z5.string().optional(),
-        recordingId: z5.string().optional(),
-        limit: z5.number().optional()
+        pageId: z6.string().optional(),
+        recordingId: z6.string().optional(),
+        limit: z6.number().optional()
       }
     },
     (input) => handleGetPerformanceReport(ctx, input)
@@ -1039,7 +1219,7 @@ function registerPerformanceTools(server, ctx) {
     {
       description: "Take a heap snapshot with CDP.",
       inputSchema: {
-        pageId: z5.string().optional()
+        pageId: z6.string().optional()
       }
     },
     async (input) => handleTakeHeapSnapshot(ctx, input)
@@ -1296,7 +1476,7 @@ function toStructuredRecord(value) {
 }
 
 // src/mcp/tools/pages.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // src/plugin/entryDiscovery.ts
 import fs from "fs";
@@ -1321,10 +1501,10 @@ function walkHtmlEntries(root, dir, entries) {
     if (!item.isFile() || !item.name.endsWith(".html")) {
       continue;
     }
-    const relative2 = normalizePath(path.relative(root, fullPath));
+    const relative3 = normalizePath(path.relative(root, fullPath));
     entries.push({
-      file: relative2,
-      pathname: relative2 === "index.html" ? "/" : `/${relative2}`
+      file: relative3,
+      pathname: relative3 === "index.html" ? "/" : `/${relative3}`
     });
   }
 }
@@ -1336,7 +1516,7 @@ function registerPageTools(server, ctx, vite) {
     {
       description: "List Vite page entries and connected runtime/CDP targets.",
       inputSchema: {
-        includeDisconnected: z6.boolean().optional()
+        includeDisconnected: z7.boolean().optional()
       }
     },
     async (input) => {
@@ -1359,8 +1539,8 @@ function registerPageTools(server, ctx, vite) {
     {
       description: "Reload the selected page. CDP uses ignoreCache; Runtime Hook falls back to normal reload.",
       inputSchema: {
-        pageId: z6.string().optional(),
-        ignoreCache: z6.boolean().optional()
+        pageId: z7.string().optional(),
+        ignoreCache: z7.boolean().optional()
       }
     },
     async (input) => {
@@ -1512,7 +1692,7 @@ function getPathname(url) {
 }
 
 // src/mcp/tools/storage.ts
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // src/cdp/cdpStorage.ts
 function createCdpStorageAdapter(client) {
@@ -1756,7 +1936,7 @@ function registerStorageTools(server, ctx) {
   registerStorageTool(server, MCP_TOOL_NAMES.listStorage, {
     description: "List same-origin storage and CDP cookies when available.",
     inputSchema: {
-      pageId: z7.string().optional()
+      pageId: z8.string().optional()
     },
     action: "list",
     handler: (input) => handleListStorage(ctx, input.pageId)
@@ -1800,23 +1980,23 @@ function registerStorageTool(server, name, options) {
 }
 function createStorageInputSchema() {
   return {
-    pageId: z7.string().optional(),
-    scope: z7.enum(["localStorage", "sessionStorage", "indexedDB", "cookie"]).optional(),
-    key: z7.string().optional(),
-    value: z7.string().optional(),
-    databaseName: z7.string().optional(),
-    objectStoreName: z7.string().optional(),
-    indexName: z7.string().optional(),
-    cookie: z7.object({
-      name: z7.string(),
-      value: z7.string().optional(),
-      domain: z7.string().optional(),
-      path: z7.string().optional(),
-      url: z7.string().optional(),
-      httpOnly: z7.boolean().optional(),
-      secure: z7.boolean().optional(),
-      sameSite: z7.enum(["strict", "lax", "none"]).optional(),
-      expires: z7.number().optional()
+    pageId: z8.string().optional(),
+    scope: z8.enum(["localStorage", "sessionStorage", "indexedDB", "cookie"]).optional(),
+    key: z8.string().optional(),
+    value: z8.string().optional(),
+    databaseName: z8.string().optional(),
+    objectStoreName: z8.string().optional(),
+    indexName: z8.string().optional(),
+    cookie: z8.object({
+      name: z8.string(),
+      value: z8.string().optional(),
+      domain: z8.string().optional(),
+      path: z8.string().optional(),
+      url: z8.string().optional(),
+      httpOnly: z8.boolean().optional(),
+      secure: z8.boolean().optional(),
+      sameSite: z8.enum(["strict", "lax", "none"]).optional(),
+      expires: z8.number().optional()
     }).optional()
   };
 }
@@ -1934,7 +2114,7 @@ function hasCdpConfig2(ctx) {
 }
 
 // src/mcp/tools/screenshot.ts
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 
 // src/cdp/cdpScreenshot.ts
 async function cdpCaptureScreenshot(options) {
@@ -2094,14 +2274,14 @@ function createProjectRelativePath(ctx, filePath) {
 var DEFAULT_SCREENSHOT_TARGET = "viewport";
 var DEFAULT_SCREENSHOT_FORMAT = "png";
 var screenshotInputSchema = {
-  pageId: z8.string().optional(),
-  target: z8.enum(["viewport", "fullPage", "element"]).optional(),
-  selector: z8.string().optional(),
-  format: z8.enum(["png", "jpeg", "webp"]).optional(),
-  prefer: z8.enum(["auto", "cdp", "runtime"]).optional(),
-  quality: z8.number().optional(),
-  scale: z8.number().optional(),
-  snapdom: z8.record(z8.string(), z8.unknown()).optional()
+  pageId: z9.string().optional(),
+  target: z9.enum(["viewport", "fullPage", "element"]).optional(),
+  selector: z9.string().optional(),
+  format: z9.enum(["png", "jpeg", "webp"]).optional(),
+  prefer: z9.enum(["auto", "cdp", "runtime"]).optional(),
+  quality: z9.number().optional(),
+  scale: z9.number().optional(),
+  snapdom: z9.record(z9.string(), z9.unknown()).optional()
 };
 function registerScreenshotTools(server, ctx) {
   server.registerTool(
@@ -2221,7 +2401,7 @@ function isScreenshotImagePayload(result) {
 
 // src/mcp/tools/vue.ts
 import { nanoid as nanoid3 } from "nanoid";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function registerVueTools(server, ctx) {
   server.registerTool(
     MCP_TOOL_NAMES.getComponentTree,
@@ -2234,7 +2414,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.getComponentState,
     {
       description: "Get Vue component state.",
-      inputSchema: { componentName: z9.string() }
+      inputSchema: { componentName: z10.string() }
     },
     async ({ componentName }) => requestVueData(ctx, (event) => {
       void ctx.rpcServer?.getInspectorState({ event, componentName });
@@ -2245,10 +2425,10 @@ function registerVueTools(server, ctx) {
     {
       description: "Edit Vue component state.",
       inputSchema: {
-        componentName: z9.string(),
-        path: z9.array(z9.string()),
-        value: z9.string(),
-        valueType: z9.enum(["string", "number", "boolean", "object", "array"])
+        componentName: z10.string(),
+        path: z10.array(z10.string()),
+        value: z10.string(),
+        valueType: z10.enum(["string", "number", "boolean", "object", "array"])
       }
     },
     ({ componentName, path: path8, value, valueType }) => {
@@ -2268,7 +2448,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.highlightComponent,
     {
       description: "Highlight a Vue component.",
-      inputSchema: { componentName: z9.string() }
+      inputSchema: { componentName: z10.string() }
     },
     ({ componentName }) => {
       if (!ctx.rpcServer) {
@@ -2296,7 +2476,7 @@ function registerVueTools(server, ctx) {
     MCP_TOOL_NAMES.getPiniaState,
     {
       description: "Get Pinia store state.",
-      inputSchema: { storeName: z9.string() }
+      inputSchema: { storeName: z10.string() }
     },
     async ({ storeName }) => requestVueData(ctx, (event) => {
       void ctx.rpcServer?.getPiniaState({ event, storeName });
@@ -2339,6 +2519,7 @@ function createMcpServer(ctx, vite) {
   });
   registerPageTools(server, ctx, vite);
   registerDomTools(server, ctx);
+  registerElementContextTools(server, ctx);
   registerScreenshotTools(server, ctx);
   registerConsoleTools(server, ctx);
   registerEvaluateTools(server, ctx);
@@ -2420,6 +2601,10 @@ function createServerVueRuntimeRpc(ctx) {
     onDomQueryUpdated: (event, data) => {
       void ctx.hooks.callHook(event, data);
     },
+    getElementContext: () => void 0,
+    onElementContextUpdated: (event, data) => {
+      void ctx.hooks.callHook(event, data);
+    },
     reloadPage: () => void 0,
     onPageReloaded: (event, data) => {
       void ctx.hooks.callHook(event, data);
@@ -2732,6 +2917,82 @@ async function startCdpObservers(ctx, target, client) {
   }
 }
 
+// src/plugin/elementInstrumentation.ts
+import { parse } from "@vue/compiler-sfc";
+import MagicString from "magic-string";
+import { relative as relative2 } from "path";
+var VUE_FILE_SUFFIX = ".vue";
+var ELEMENT_NODE_TYPE = 1;
+var SKIPPED_TAGS = /* @__PURE__ */ new Set(["template", "slot", "script", "style"]);
+var MCP_ID_ATTR = "data-v-mcp-id";
+function createElementInstrumentationController(options) {
+  return {
+    transform(code, id, ssr) {
+      if (ssr || shouldSkipInstrumentation(id)) {
+        return void 0;
+      }
+      const filename = id.split("?", 1)[0];
+      if (!filename.endsWith(VUE_FILE_SUFFIX)) {
+        return void 0;
+      }
+      const parsed = parse(code, { filename });
+      const template = parsed.descriptor.template;
+      if (!template?.ast) {
+        return void 0;
+      }
+      const s = new MagicString(code);
+      const relativeFile = normalizePath2(relative2(options.root, filename));
+      for (const node of template.ast.children) {
+        injectNodeId(s, node, relativeFile);
+      }
+      if (!s.hasChanged()) {
+        return void 0;
+      }
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: true })
+      };
+    }
+  };
+}
+function shouldSkipInstrumentation(id) {
+  if (id.startsWith("\0")) {
+    return true;
+  }
+  const normalized = normalizePath2(id);
+  if (normalized.includes("/node_modules/")) {
+    return true;
+  }
+  return !normalized.startsWith("/") && !/^[A-Za-z]:\//.test(normalized);
+}
+function normalizePath2(path8) {
+  return path8.replace(/\\/g, "/");
+}
+function injectNodeId(s, node, relativeFile) {
+  if (node.type !== ELEMENT_NODE_TYPE || !node.tag || !node.loc) {
+    return;
+  }
+  if (!SKIPPED_TAGS.has(node.tag) && !hasMcpIdAttr(node)) {
+    const id = `${relativeFile}:${String(node.loc.start.line)}:${String(node.loc.start.column)}`;
+    const insertAt = node.loc.start.offset + node.tag.length + 1;
+    s.appendLeft(insertAt, ` ${MCP_ID_ATTR}="${id}"`);
+  }
+  for (const child of node.children ?? []) {
+    injectNodeId(s, child, relativeFile);
+  }
+}
+function hasMcpIdAttr(node) {
+  return (node.props ?? []).some((prop) => {
+    if (!isTemplateProp(prop)) {
+      return false;
+    }
+    return prop.name === MCP_ID_ATTR;
+  });
+}
+function isTemplateProp(value) {
+  return Boolean(value && typeof value === "object" && "name" in value);
+}
+
 // src/plugin/injectRuntime.ts
 import { createRequire } from "module";
 import { join } from "path";
@@ -2751,7 +3012,7 @@ function createRuntimeInjectionController(options, getConfig) {
     },
     load(id) {
       if (id === RESOLVED_VIRTUAL_RUNTIME_ID) {
-        return createRuntimeModule();
+        return createRuntimeModule(options, getConfig()?.root);
       }
       if (id === RESOLVED_VIRTUAL_SCREENSHOT_CONFIG_ID) {
         return createScreenshotConfigModule(options);
@@ -2794,14 +3055,17 @@ ${code}`;
     }
   };
 }
-function createRuntimeModule() {
+function createRuntimeModule(options, root) {
   return [
     "import { setScreenshotModuleRegistry, setSnapdomLoader, startRuntimeClient } from '@xiaou66/vite-plugin-vue-mcp-next/runtime/client';",
     `import { screenshotModuleRegistry } from '${VIRTUAL_SCREENSHOT_CONFIG_ID}';`,
     `import { loadSnapdom } from '${VIRTUAL_SNAPDOM_LOADER_ID}';`,
     "setScreenshotModuleRegistry(screenshotModuleRegistry);",
     "setSnapdomLoader(loadSnapdom);",
-    "void startRuntimeClient();"
+    `void startRuntimeClient(${JSON.stringify({
+      elementPicker: options.elementPicker,
+      projectRoot: root
+    })});`
   ].join("\n");
 }
 function createSnapdomLoaderModule(root) {
@@ -3320,6 +3584,7 @@ function vueMcpNext(userOptions = {}) {
     options,
     () => config
   );
+  let elementInstrumentation;
   const cdpLifecycle = createCdpLifecycleController(ctx);
   ctx.cdpLifecycle = cdpLifecycle;
   return {
@@ -3328,6 +3593,9 @@ function vueMcpNext(userOptions = {}) {
     apply: "serve",
     configResolved(resolvedConfig) {
       config = resolvedConfig;
+      elementInstrumentation = createElementInstrumentationController({
+        root: resolvedConfig.root
+      });
     },
     async configureServer(server) {
       ctx.server = server;
@@ -3344,32 +3612,53 @@ function vueMcpNext(userOptions = {}) {
         () => createMcpServer(ctx, server),
         server
       );
-      server.ws.on(
-        "vite-plugin-vue-mcp-next:page-connected",
-        (payload) => {
-          if (isRuntimePageTarget(payload)) {
-            ctx.pages.upsert(payload);
-            void ctx.hooks.callHook(RUNTIME_PAGE_RECONNECTED_EVENT, payload);
-            void cdpLifecycle.connectPage(payload);
+      const lastSeenAt = /* @__PURE__ */ new Map();
+      const heartbeatTimer = setInterval(() => {
+        const now = Date.now();
+        for (const [pageId, seenAt] of lastSeenAt) {
+          const target = ctx.pages.get(pageId);
+          if (!target || target.source !== "runtime" || !target.connected) {
+            lastSeenAt.delete(pageId);
+            continue;
           }
-        }
-      );
-      server.ws.on(
-        "vite-plugin-vue-mcp-next:console-record",
-        (payload) => {
-          if (isConsoleRecord(payload)) {
-            ctx.consoleRecords.push(payload);
+          if (now - seenAt >= DEFAULT_RUNTIME_PAGE_HEARTBEAT_TIMEOUT_MS) {
+            ctx.pages.disconnect(pageId, now);
+            lastSeenAt.delete(pageId);
           }
         }
-      );
-      server.ws.on(
-        "vite-plugin-vue-mcp-next:network-record",
-        (payload) => {
-          if (isNetworkRecord(payload)) {
-            ctx.networkRecords.push(payload);
+      }, DEFAULT_RUNTIME_PAGE_HEARTBEAT_SCAN_INTERVAL_MS);
+      server.ws.on(RUNTIME_PAGE_CONNECTED_EVENT, (payload) => {
+        if (isRuntimePageTarget(payload)) {
+          ctx.pages.upsert(payload);
+          lastSeenAt.set(payload.pageId, Date.now());
+          void ctx.hooks.callHook(RUNTIME_PAGE_RECONNECTED_EVENT, payload);
+          void cdpLifecycle.connectPage(payload);
+        }
+      });
+      server.ws.on(RUNTIME_PAGE_HEARTBEAT_EVENT, (payload) => {
+        if (isRuntimeHeartbeatTarget(payload)) {
+          const target = ctx.pages.get(payload.pageId);
+          if (target?.source === "runtime" && target.connected) {
+            lastSeenAt.set(payload.pageId, payload.timestamp);
           }
         }
-      );
+      });
+      server.ws.on(RUNTIME_PAGE_DISCONNECTED_EVENT, (payload) => {
+        if (isRuntimeDisconnectTarget(payload)) {
+          ctx.pages.disconnect(payload.pageId);
+          lastSeenAt.delete(payload.pageId);
+        }
+      });
+      server.ws.on("vite-plugin-vue-mcp-next:console-record", (payload) => {
+        if (isConsoleRecord(payload)) {
+          ctx.consoleRecords.push(payload);
+        }
+      });
+      server.ws.on("vite-plugin-vue-mcp-next:network-record", (payload) => {
+        if (isNetworkRecord(payload)) {
+          ctx.networkRecords.push(payload);
+        }
+      });
       server.ws.on(
         "vite-plugin-vue-mcp-next:performance-record",
         (payload) => {
@@ -3399,6 +3688,7 @@ function vueMcpNext(userOptions = {}) {
         }, 300);
       }
       server.httpServer?.once("close", () => {
+        clearInterval(heartbeatTimer);
         void cdpLifecycle.closeAll();
       });
     },
@@ -3409,7 +3699,21 @@ function vueMcpNext(userOptions = {}) {
       return runtimeInjection.load(id);
     },
     transform(code, id, transformOptions) {
-      return runtimeInjection.transform(code, id, transformOptions?.ssr);
+      const instrumented = elementInstrumentation?.transform(
+        code,
+        id,
+        transformOptions?.ssr
+      );
+      const nextCode = instrumented && typeof instrumented === "object" && "code" in instrumented && typeof instrumented.code === "string" ? instrumented.code : code;
+      const runtimeInjected = runtimeInjection.transform(
+        nextCode,
+        id,
+        transformOptions?.ssr
+      );
+      if (runtimeInjected) {
+        return runtimeInjected;
+      }
+      return instrumented;
     },
     transformIndexHtml(html) {
       return runtimeInjection.transformIndexHtml(html);
@@ -3423,6 +3727,20 @@ function isRuntimePageTarget(payload) {
   const target = payload;
   return target.source === "runtime" && typeof target.pageId === "string" && typeof target.url === "string" && typeof target.pathname === "string" && typeof target.connected === "boolean" && (target.runtimeClientId === void 0 || typeof target.runtimeClientId === "string");
 }
+function isRuntimeHeartbeatTarget(payload) {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+  const target = payload;
+  return typeof target.pageId === "string" && typeof target.timestamp === "number";
+}
+function isRuntimeDisconnectTarget(payload) {
+  if (!payload || typeof payload !== "object") {
+    return false;
+  }
+  const target = payload;
+  return typeof target.pageId === "string";
+}
 function isConsoleRecord(payload) {
   if (!payload || typeof payload !== "object") {
     return false;