@aipanel/core 1.2.19 → 1.2.20

package/es/common/constants.d.ts

@@ -45,7 +45,7 @@ export declare const HOST_EVENTS_API_PATH = "/__aipanel_host_events__";
 export declare const CONTEXT_UPDATE_INTERVAL = 500;
 /** 服务器同步间隔（毫秒） */
 export declare const SERVER_SYNC_INTERVAL = 2000;
-/** Vue Inspector 检查间隔（毫秒） */
+/** 框架 Inspector 检查间隔（毫秒） */
 export declare const INSPECTOR_CHECK_INTERVAL = 500;
 /** 自动打开延迟（毫秒） */
 export declare const AUTO_OPEN_DELAY = 1000;
@@ -185,3 +185,14 @@ export declare const SSE_EVENT_TYPES: {
     readonly CLEAR_ELEMENTS: "CLEAR_ELEMENTS";
 };
 export type SSEEventType = (typeof SSE_EVENT_TYPES)[keyof typeof SSE_EVENT_TYPES];
+/** ==================== 元素选择器（click-to-source） ==================== */
+/**
+ * 元素选择器适配器标识：服务端注入的构建期插件与客户端运行时适配器共用同一标识，
+ * 已登记 Vue / React；新增框架在此登记，两侧按同一 id 对齐。
+ */
+export declare const INSPECTOR_ADAPTER_IDS: {
+    readonly vue: "vue";
+    readonly react: "react";
+};
+/** 元素选择器适配器标识类型 */
+export type InspectorAdapterId = (typeof INSPECTOR_ADAPTER_IDS)[keyof typeof INSPECTOR_ADAPTER_IDS];

package/es/common/constants.mjs

@@ -106,6 +106,10 @@ const SSE_EVENT_TYPES = {
   SESSION_EVENT: "SESSION_EVENT",
   CLEAR_ELEMENTS: "CLEAR_ELEMENTS"
 };
+const INSPECTOR_ADAPTER_IDS = {
+  vue: "vue",
+  react: "react"
+};
 export {
   AIPANEL_CACHE_DIR,
   AUTO_OPEN_DELAY,
@@ -124,6 +128,7 @@ export {
   EXT_MSG,
   HOST_EVENTS_API_PATH,
   INIT_MARKER,
+  INSPECTOR_ADAPTER_IDS,
   INSPECTOR_CHECK_INTERVAL,
   LOGS_API_PATH,
   LOG_PREFIX,

package/es/common/inspector/index.d.ts

@@ -0,0 +1,6 @@
+import type { InspectorAdapter } from "./types";
+export * from "./types";
+/** 全部已登记适配器：用于静态元数据（忽略标记、源码位置解析） */
+export declare function listInspectorAdapters(): readonly InspectorAdapter[];
+/** 当前可用的适配器（对应框架的 inspector 运行时已注入页面）；无可用返回 null */
+export declare function resolveInspectorAdapter(): InspectorAdapter | null;

package/es/common/inspector/index.mjs

@@ -0,0 +1,14 @@
+import { reactInspectorAdapter } from "./react.mjs";
+import { vueInspectorAdapter } from "./vue.mjs";
+export * from "./types.mjs";
+const adapters = [vueInspectorAdapter, reactInspectorAdapter];
+function listInspectorAdapters() {
+  return adapters;
+}
+function resolveInspectorAdapter() {
+  return adapters.find((adapter) => adapter.isAvailable()) ?? null;
+}
+export {
+  listInspectorAdapters,
+  resolveInspectorAdapter
+};

package/es/common/inspector/react.d.ts

@@ -0,0 +1,8 @@
+import { type InspectorAdapter } from "./types";
+/**
+ * React 适配器：构建期由 vite 集成（@code-inspector/core transformCode）注入
+ * data-insp-path 源码坐标标记，运行时按「注入标记 → react-dev-inspector 兼容属性 →
+ * fiber._debugSource」依次解析；React 无底层 inspector 运行时，
+ * 点击接管由适配器自装的 document 捕获监听实现。
+ */
+export declare const reactInspectorAdapter: InspectorAdapter;

package/es/common/inspector/react.mjs

@@ -0,0 +1,105 @@
+import { INSPECTOR_ADAPTER_IDS } from "../constants.mjs";
+import {
+  parseSourceLocation
+} from "./types.mjs";
+const SOURCE_LOCATION_ATTRIBUTE = "data-insp-path";
+const RDI_PATH_ATTRIBUTE = "data-inspector-relative-path";
+const RDI_LINE_ATTRIBUTE = "data-inspector-line";
+const RDI_COLUMN_ATTRIBUTE = "data-inspector-column";
+const FIBER_KEY_PREFIX = "__reactFiber$";
+const CONTAINER_KEY_PREFIX = "__reactContainer$";
+const FIBER_WALK_LIMIT = 50;
+const DETECT_SCAN_LIMIT = 200;
+let clickHandler = null;
+let listenerInstalled = false;
+let enabled = false;
+function hasFiberKey(element) {
+  const keys = Object.keys(element);
+  return keys.some(
+    (key) => key.startsWith(FIBER_KEY_PREFIX) || key.startsWith(CONTAINER_KEY_PREFIX)
+  );
+}
+function detectReactRuntime() {
+  if (typeof document === "undefined") return false;
+  const roots = document.querySelectorAll("#root, #__next, [data-reactroot]");
+  for (const element of [document.body, ...roots]) {
+    if (element && hasFiberKey(element)) return true;
+  }
+  const descendants = document.body?.querySelectorAll("*") ?? [];
+  const limit = Math.min(descendants.length, DETECT_SCAN_LIMIT);
+  for (let index = 0; index < limit; index += 1) {
+    if (hasFiberKey(descendants[index])) return true;
+  }
+  return false;
+}
+function resolveFromAttributes(element) {
+  const marker = element.getAttribute(SOURCE_LOCATION_ATTRIBUTE);
+  if (marker) {
+    const location = parseSourceLocation(marker.replace(/:[^:]*$/, ""));
+    if (location) return location;
+  }
+  const rdiPath = element.getAttribute(RDI_PATH_ATTRIBUTE);
+  if (rdiPath) {
+    return {
+      file: rdiPath,
+      line: Number.parseInt(element.getAttribute(RDI_LINE_ATTRIBUTE) ?? "", 10) || null,
+      column: Number.parseInt(element.getAttribute(RDI_COLUMN_ATTRIBUTE) ?? "", 10) || null
+    };
+  }
+  return null;
+}
+function resolveFromFiber(element) {
+  const fiberKey = Object.keys(element).find((key) => key.startsWith(FIBER_KEY_PREFIX));
+  let fiber = fiberKey ? element[fiberKey] : null;
+  for (let depth = 0; fiber && depth < FIBER_WALK_LIMIT; depth += 1) {
+    const source = fiber._debugSource;
+    if (source?.fileName) {
+      return {
+        file: source.fileName,
+        line: source.lineNumber ?? null,
+        // React 的 columnNumber 为 0 基，统一转 1 基（与编辑器跳转一致）
+        column: source.columnNumber != null ? source.columnNumber + 1 : null
+      };
+    }
+    fiber = fiber.return;
+  }
+  return null;
+}
+function handleDocumentClick(event) {
+  if (!enabled) return;
+  const element = event.target instanceof Element ? event.target : null;
+  if (clickHandler?.(element, event)) {
+    event.preventDefault();
+    event.stopPropagation();
+  }
+}
+const reactInspectorAdapter = {
+  id: INSPECTOR_ADAPTER_IDS.react,
+  label: "React Inspector",
+  ignoreSelectors: [],
+  ignoreAttributes: [],
+  isAvailable() {
+    return detectReactRuntime();
+  },
+  resolveSourceLocation(element) {
+    let current = element;
+    while (current) {
+      const location = resolveFromAttributes(current) ?? resolveFromFiber(current);
+      if (location?.file) return location;
+      current = current.parentElement;
+    }
+    return null;
+  },
+  onElementClick(handler) {
+    clickHandler = handler;
+    if (listenerInstalled) return;
+    document.addEventListener("click", handleDocumentClick, true);
+    listenerInstalled = true;
+  },
+  setEnabled(next) {
+    enabled = next;
+  }
+};
+export {
+  reactInspectorAdapter
+};

package/es/common/inspector/types.d.ts

@@ -0,0 +1,35 @@
+import type { InspectorAdapterId } from "../constants";
+/** 元素对应的源码位置（跨框架统一形态；未解析到的字段为 null） */
+export interface InspectorSourceLocation {
+    file: string | null;
+    line: number | null;
+    column: number | null;
+}
+/**
+ * 元素点击处理器。
+ * 返回 true 表示宿主已接管：适配器抑制底层 inspector 的默认行为（如打开编辑器）。
+ */
+export type InspectorElementClickHandler = (element: Element | null, event: MouseEvent) => boolean;
+/**
+ * 框架侧「点击元素 → 源码位置」适配器契约。
+ * 宿主（挂件 / 扩展）只依赖此接口，不感知 Vue、React 等框架差异。
+ */
+export interface InspectorAdapter {
+    readonly id: InspectorAdapterId;
+    /** 用户可见名称（提示文案用） */
+    readonly label: string;
+    /** 运行时是否可用（对应框架的 inspector 已注入页面） */
+    isAvailable(): boolean;
+    /** 适配器自身覆盖层的选择器：宿主需忽略，不参与选择 */
+    readonly ignoreSelectors: readonly string[];
+    /** 适配器自带的忽略标记属性：宿主需忽略，不参与选择 */
+    readonly ignoreAttributes: readonly string[];
+    /** 元素 → 源码位置；解析不到返回 null */
+    resolveSourceLocation(element: Element): InspectorSourceLocation | null;
+    /** 注册元素点击处理器（幂等：同一底层 inspector 只安装一次） */
+    onElementClick(handler: InspectorElementClickHandler): void;
+    /** 同步底层 inspector 的启用状态 */
+    setEnabled(enabled: boolean): void;
+}
+/** 解析 "文件:行:列" 形式的源码坐标（各框架适配器共用的标记格式） */
+export declare function parseSourceLocation(value: string): InspectorSourceLocation | null;

package/es/common/inspector/types.mjs

@@ -0,0 +1,12 @@
+function parseSourceLocation(value) {
+  const match = /^(.+):([\d]+):([\d]+)$/.exec(value);
+  if (!match) return null;
+  return {
+    file: match[1],
+    line: Number.parseInt(match[2], 10),
+    column: Number.parseInt(match[3], 10)
+  };
+}
+export {
+  parseSourceLocation
+};

package/es/common/inspector/vue.d.ts

@@ -0,0 +1,20 @@
+import { type InspectorAdapter } from "./types";
+/** unplugin-vue-inspector 暴露到页面的运行时控制对象 */
+interface VueInspectorRuntime {
+    handleClick: (e: MouseEvent) => void;
+    enable: () => void;
+    disable: () => void;
+    /** AIPanel 已接管 handleClick 的标记（幂等安装） */
+    __aipanel_hooked?: boolean;
+}
+declare global {
+    interface Window {
+        __VUE_INSPECTOR__?: VueInspectorRuntime;
+    }
+}
+/**
+ * Vue 适配器：复用 unplugin-vue-inspector 注入的运行时与源码坐标标记，
+ * 在宿主选择模式下接管点击、解析元素源码位置。
+ */
+export declare const vueInspectorAdapter: InspectorAdapter;
+export {};

package/es/common/inspector/vue.mjs

@@ -0,0 +1,120 @@
+import { INSPECTOR_ADAPTER_IDS } from "../constants.mjs";
+import {
+  parseSourceLocation
+} from "./types.mjs";
+const SOURCE_LOCATION_ATTRIBUTE = "data-v-inspector";
+const VNODE_SOURCE_KEY = "__v_inspector";
+const IGNORE_ATTRIBUTE = "data-v-inspector-ignore";
+const OVERLAY_SELECTOR = "#vue-inspector-container";
+function getRuntime() {
+  return typeof window === "undefined" ? void 0 : window.__VUE_INSPECTOR__;
+}
+function isAdapterOwned(element) {
+  return element.hasAttribute(IGNORE_ATTRIBUTE) || Boolean(element.closest(OVERLAY_SELECTOR));
+}
+function getMarkerData(element) {
+  const vnodeData = element.__vnode?.props?.[VNODE_SOURCE_KEY];
+  if (vnodeData) return vnodeData;
+  const ctxVNode = element.__vnode?.ctx?.vnode;
+  if (ctxVNode?.el === element) {
+    const ctxData = ctxVNode.props?.[VNODE_SOURCE_KEY];
+    if (ctxData) return ctxData;
+  }
+  const vueInstance = element.__vueParentComponent;
+  let currentParent = vueInstance?.parent;
+  while (currentParent) {
+    if (currentParent.vnode?.el === element) {
+      const parentData = currentParent.vnode.props?.[VNODE_SOURCE_KEY];
+      if (parentData) return parentData;
+    }
+    currentParent = currentParent.parent;
+  }
+  return element.getAttribute(SOURCE_LOCATION_ATTRIBUTE) ?? void 0;
+}
+function resolveFromMarker(element) {
+  const data = getMarkerData(element);
+  return data ? parseSourceLocation(data) : null;
+}
+function resolveFromVueInstance(element) {
+  const vue3Instance = element.__vueParentComponent;
+  if (vue3Instance) {
+    let current = vue3Instance;
+    while (current) {
+      const file = current.type?.__file || current.vnode?.type?.__file;
+      if (file) {
+        return { file, line: null, column: null };
+      }
+      current = current.parent;
+    }
+  }
+  const vue2Instance = element.__vue__;
+  if (vue2Instance) {
+    let current = vue2Instance;
+    while (current) {
+      const file = current.$options?.__file;
+      if (file) {
+        return { file, line: null, column: null };
+      }
+      current = current.$parent;
+    }
+  }
+  return null;
+}
+function mergeSourceLocations(markerLocation, instanceLocation) {
+  if (!markerLocation?.file && !instanceLocation?.file) return null;
+  if (markerLocation?.file && instanceLocation?.file) {
+    const isNodeModules = (path) => path.includes("node_modules");
+    if (!isNodeModules(markerLocation.file)) return markerLocation;
+    if (!isNodeModules(instanceLocation.file)) return instanceLocation;
+    return markerLocation;
+  }
+  return markerLocation?.file ? markerLocation : instanceLocation;
+}
+let clickHandler = null;
+const vueInspectorAdapter = {
+  id: INSPECTOR_ADAPTER_IDS.vue,
+  label: "Vue Inspector",
+  ignoreSelectors: [OVERLAY_SELECTOR],
+  ignoreAttributes: [IGNORE_ATTRIBUTE],
+  isAvailable() {
+    return Boolean(getRuntime());
+  },
+  resolveSourceLocation(element) {
+    let current = element;
+    let markerLocation = null;
+    let instanceLocation = null;
+    while (current && !(markerLocation && instanceLocation)) {
+      if (!isAdapterOwned(current)) {
+        markerLocation ?? (markerLocation = resolveFromMarker(current));
+        instanceLocation ?? (instanceLocation = resolveFromVueInstance(current));
+      }
+      current = current.parentElement;
+    }
+    return mergeSourceLocations(markerLocation, instanceLocation);
+  },
+  onElementClick(handler) {
+    clickHandler = handler;
+    const runtime = getRuntime();
+    if (!runtime || runtime.__aipanel_hooked) return;
+    const originalHandleClick = runtime.handleClick.bind(runtime);
+    runtime.handleClick = (event) => {
+      const element = event.target instanceof Element ? event.target : null;
+      if (clickHandler?.(element, event)) {
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
+      originalHandleClick(event);
+    };
+    runtime.__aipanel_hooked = true;
+  },
+  setEnabled(enabled) {
+    const runtime = getRuntime();
+    if (!runtime) return;
+    if (enabled) runtime.enable();
+    else runtime.disable();
+  }
+};
+export {
+  vueInspectorAdapter
+};

package/es/common/types.d.ts

@@ -113,6 +113,18 @@ export interface PageContext {
  * 服务启动任务状态
  */
 export type ServiceStartupTask = "checking_provider" | "allocating_port" | "preparing_runtime" | "starting_web" | "waiting_web_ready" | "starting_proxy" | "warming_up_chrome" | "creating_session" | "provider_not_installed" | "web_start_timeout" | "proxy_start_failed" | "session_creation_failed" | "chrome_mcp_failed" | "ready";
+/**
+ * 服务启动任务状态载荷
+ * currentTask / SSE TASK_UPDATE / STATUS_SYNC 共用同一形态（单一来源）
+ */
+export interface ServiceTaskState {
+    /** 当前任务 */
+    task: ServiceStartupTask;
+    /** 失败原因类型（如 ChromeMcpWarmupErrorType） */
+    errorType?: string;
+    /** 失败原因文案 */
+    errorMessage?: string;
+}
 /**
  * 服务启动任务状态映射
  */

package/es/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./common/constants";
+export * from "./common/inspector";
 export * from "./common/logger-core";
 export * from "./common/options";
 export * from "./common/provider";

package/es/index.mjs

@@ -1,4 +1,5 @@
 export * from "./common/constants.mjs";
+export * from "./common/inspector/index.mjs";
 export * from "./common/logger-core.mjs";
 export * from "./common/options.mjs";
 export * from "./common/provider.mjs";

package/lib/common/constants.cjs

@@ -34,6 +34,7 @@ __export(constants_exports, {
   EXT_MSG: () => EXT_MSG,
   HOST_EVENTS_API_PATH: () => HOST_EVENTS_API_PATH,
   INIT_MARKER: () => INIT_MARKER,
+  INSPECTOR_ADAPTER_IDS: () => INSPECTOR_ADAPTER_IDS,
   INSPECTOR_CHECK_INTERVAL: () => INSPECTOR_CHECK_INTERVAL,
   LOGS_API_PATH: () => LOGS_API_PATH,
   LOG_PREFIX: () => LOG_PREFIX,
@@ -174,6 +175,10 @@ const SSE_EVENT_TYPES = {
   SESSION_EVENT: "SESSION_EVENT",
   CLEAR_ELEMENTS: "CLEAR_ELEMENTS"
 };
+const INSPECTOR_ADAPTER_IDS = {
+  vue: "vue",
+  react: "react"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AIPANEL_CACHE_DIR,
@@ -193,6 +198,7 @@ const SSE_EVENT_TYPES = {
   EXT_MSG,
   HOST_EVENTS_API_PATH,
   INIT_MARKER,
+  INSPECTOR_ADAPTER_IDS,
   INSPECTOR_CHECK_INTERVAL,
   LOGS_API_PATH,
   LOG_PREFIX,

package/lib/common/constants.d.ts

@@ -45,7 +45,7 @@ export declare const HOST_EVENTS_API_PATH = "/__aipanel_host_events__";
 export declare const CONTEXT_UPDATE_INTERVAL = 500;
 /** 服务器同步间隔（毫秒） */
 export declare const SERVER_SYNC_INTERVAL = 2000;
-/** Vue Inspector 检查间隔（毫秒） */
+/** 框架 Inspector 检查间隔（毫秒） */
 export declare const INSPECTOR_CHECK_INTERVAL = 500;
 /** 自动打开延迟（毫秒） */
 export declare const AUTO_OPEN_DELAY = 1000;
@@ -185,3 +185,14 @@ export declare const SSE_EVENT_TYPES: {
     readonly CLEAR_ELEMENTS: "CLEAR_ELEMENTS";
 };
 export type SSEEventType = (typeof SSE_EVENT_TYPES)[keyof typeof SSE_EVENT_TYPES];
+/** ==================== 元素选择器（click-to-source） ==================== */
+/**
+ * 元素选择器适配器标识：服务端注入的构建期插件与客户端运行时适配器共用同一标识，
+ * 已登记 Vue / React；新增框架在此登记，两侧按同一 id 对齐。
+ */
+export declare const INSPECTOR_ADAPTER_IDS: {
+    readonly vue: "vue";
+    readonly react: "react";
+};
+/** 元素选择器适配器标识类型 */
+export type InspectorAdapterId = (typeof INSPECTOR_ADAPTER_IDS)[keyof typeof INSPECTOR_ADAPTER_IDS];

package/lib/common/inspector/index.cjs

@@ -0,0 +1,40 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var inspector_exports = {};
+__export(inspector_exports, {
+  listInspectorAdapters: () => listInspectorAdapters,
+  resolveInspectorAdapter: () => resolveInspectorAdapter
+});
+module.exports = __toCommonJS(inspector_exports);
+var import_react = require("./react.cjs");
+var import_vue = require("./vue.cjs");
+__reExport(inspector_exports, require("./types.cjs"), module.exports);
+const adapters = [import_vue.vueInspectorAdapter, import_react.reactInspectorAdapter];
+function listInspectorAdapters() {
+  return adapters;
+}
+function resolveInspectorAdapter() {
+  return adapters.find((adapter) => adapter.isAvailable()) ?? null;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  listInspectorAdapters,
+  resolveInspectorAdapter,
+  ...require("./types.cjs")
+});

package/lib/common/inspector/index.d.ts

@@ -0,0 +1,6 @@
+import type { InspectorAdapter } from "./types";
+export * from "./types";
+/** 全部已登记适配器：用于静态元数据（忽略标记、源码位置解析） */
+export declare function listInspectorAdapters(): readonly InspectorAdapter[];
+/** 当前可用的适配器（对应框架的 inspector 运行时已注入页面）；无可用返回 null */
+export declare function resolveInspectorAdapter(): InspectorAdapter | null;

package/lib/common/inspector/react.cjs

@@ -0,0 +1,126 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var react_exports = {};
+__export(react_exports, {
+  reactInspectorAdapter: () => reactInspectorAdapter
+});
+module.exports = __toCommonJS(react_exports);
+var import_constants = require("../constants.cjs");
+var import_types = require("./types.cjs");
+const SOURCE_LOCATION_ATTRIBUTE = "data-insp-path";
+const RDI_PATH_ATTRIBUTE = "data-inspector-relative-path";
+const RDI_LINE_ATTRIBUTE = "data-inspector-line";
+const RDI_COLUMN_ATTRIBUTE = "data-inspector-column";
+const FIBER_KEY_PREFIX = "__reactFiber$";
+const CONTAINER_KEY_PREFIX = "__reactContainer$";
+const FIBER_WALK_LIMIT = 50;
+const DETECT_SCAN_LIMIT = 200;
+let clickHandler = null;
+let listenerInstalled = false;
+let enabled = false;
+function hasFiberKey(element) {
+  const keys = Object.keys(element);
+  return keys.some(
+    (key) => key.startsWith(FIBER_KEY_PREFIX) || key.startsWith(CONTAINER_KEY_PREFIX)
+  );
+}
+function detectReactRuntime() {
+  if (typeof document === "undefined") return false;
+  const roots = document.querySelectorAll("#root, #__next, [data-reactroot]");
+  for (const element of [document.body, ...roots]) {
+    if (element && hasFiberKey(element)) return true;
+  }
+  const descendants = document.body?.querySelectorAll("*") ?? [];
+  const limit = Math.min(descendants.length, DETECT_SCAN_LIMIT);
+  for (let index = 0; index < limit; index += 1) {
+    if (hasFiberKey(descendants[index])) return true;
+  }
+  return false;
+}
+function resolveFromAttributes(element) {
+  const marker = element.getAttribute(SOURCE_LOCATION_ATTRIBUTE);
+  if (marker) {
+    const location = (0, import_types.parseSourceLocation)(marker.replace(/:[^:]*$/, ""));
+    if (location) return location;
+  }
+  const rdiPath = element.getAttribute(RDI_PATH_ATTRIBUTE);
+  if (rdiPath) {
+    return {
+      file: rdiPath,
+      line: Number.parseInt(element.getAttribute(RDI_LINE_ATTRIBUTE) ?? "", 10) || null,
+      column: Number.parseInt(element.getAttribute(RDI_COLUMN_ATTRIBUTE) ?? "", 10) || null
+    };
+  }
+  return null;
+}
+function resolveFromFiber(element) {
+  const fiberKey = Object.keys(element).find((key) => key.startsWith(FIBER_KEY_PREFIX));
+  let fiber = fiberKey ? element[fiberKey] : null;
+  for (let depth = 0; fiber && depth < FIBER_WALK_LIMIT; depth += 1) {
+    const source = fiber._debugSource;
+    if (source?.fileName) {
+      return {
+        file: source.fileName,
+        line: source.lineNumber ?? null,
+        // React 的 columnNumber 为 0 基，统一转 1 基（与编辑器跳转一致）
+        column: source.columnNumber != null ? source.columnNumber + 1 : null
+      };
+    }
+    fiber = fiber.return;
+  }
+  return null;
+}
+function handleDocumentClick(event) {
+  if (!enabled) return;
+  const element = event.target instanceof Element ? event.target : null;
+  if (clickHandler?.(element, event)) {
+    event.preventDefault();
+    event.stopPropagation();
+  }
+}
+const reactInspectorAdapter = {
+  id: import_constants.INSPECTOR_ADAPTER_IDS.react,
+  label: "React Inspector",
+  ignoreSelectors: [],
+  ignoreAttributes: [],
+  isAvailable() {
+    return detectReactRuntime();
+  },
+  resolveSourceLocation(element) {
+    let current = element;
+    while (current) {
+      const location = resolveFromAttributes(current) ?? resolveFromFiber(current);
+      if (location?.file) return location;
+      current = current.parentElement;
+    }
+    return null;
+  },
+  onElementClick(handler) {
+    clickHandler = handler;
+    if (listenerInstalled) return;
+    document.addEventListener("click", handleDocumentClick, true);
+    listenerInstalled = true;
+  },
+  setEnabled(next) {
+    enabled = next;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  reactInspectorAdapter
+});

package/lib/common/inspector/react.d.ts

@@ -0,0 +1,8 @@
+import { type InspectorAdapter } from "./types";
+/**
+ * React 适配器：构建期由 vite 集成（@code-inspector/core transformCode）注入
+ * data-insp-path 源码坐标标记，运行时按「注入标记 → react-dev-inspector 兼容属性 →
+ * fiber._debugSource」依次解析；React 无底层 inspector 运行时，
+ * 点击接管由适配器自装的 document 捕获监听实现。
+ */
+export declare const reactInspectorAdapter: InspectorAdapter;

package/lib/common/inspector/types.cjs

@@ -0,0 +1,35 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+__export(types_exports, {
+  parseSourceLocation: () => parseSourceLocation
+});
+module.exports = __toCommonJS(types_exports);
+function parseSourceLocation(value) {
+  const match = /^(.+):([\d]+):([\d]+)$/.exec(value);
+  if (!match) return null;
+  return {
+    file: match[1],
+    line: Number.parseInt(match[2], 10),
+    column: Number.parseInt(match[3], 10)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseSourceLocation
+});

package/lib/common/inspector/types.d.ts

@@ -0,0 +1,35 @@
+import type { InspectorAdapterId } from "../constants";
+/** 元素对应的源码位置（跨框架统一形态；未解析到的字段为 null） */
+export interface InspectorSourceLocation {
+    file: string | null;
+    line: number | null;
+    column: number | null;
+}
+/**
+ * 元素点击处理器。
+ * 返回 true 表示宿主已接管：适配器抑制底层 inspector 的默认行为（如打开编辑器）。
+ */
+export type InspectorElementClickHandler = (element: Element | null, event: MouseEvent) => boolean;
+/**
+ * 框架侧「点击元素 → 源码位置」适配器契约。
+ * 宿主（挂件 / 扩展）只依赖此接口，不感知 Vue、React 等框架差异。
+ */
+export interface InspectorAdapter {
+    readonly id: InspectorAdapterId;
+    /** 用户可见名称（提示文案用） */
+    readonly label: string;
+    /** 运行时是否可用（对应框架的 inspector 已注入页面） */
+    isAvailable(): boolean;
+    /** 适配器自身覆盖层的选择器：宿主需忽略，不参与选择 */
+    readonly ignoreSelectors: readonly string[];
+    /** 适配器自带的忽略标记属性：宿主需忽略，不参与选择 */
+    readonly ignoreAttributes: readonly string[];
+    /** 元素 → 源码位置；解析不到返回 null */
+    resolveSourceLocation(element: Element): InspectorSourceLocation | null;
+    /** 注册元素点击处理器（幂等：同一底层 inspector 只安装一次） */
+    onElementClick(handler: InspectorElementClickHandler): void;
+    /** 同步底层 inspector 的启用状态 */
+    setEnabled(enabled: boolean): void;
+}
+/** 解析 "文件:行:列" 形式的源码坐标（各框架适配器共用的标记格式） */
+export declare function parseSourceLocation(value: string): InspectorSourceLocation | null;

package/lib/common/inspector/vue.cjs

@@ -0,0 +1,141 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var vue_exports = {};
+__export(vue_exports, {
+  vueInspectorAdapter: () => vueInspectorAdapter
+});
+module.exports = __toCommonJS(vue_exports);
+var import_constants = require("../constants.cjs");
+var import_types = require("./types.cjs");
+const SOURCE_LOCATION_ATTRIBUTE = "data-v-inspector";
+const VNODE_SOURCE_KEY = "__v_inspector";
+const IGNORE_ATTRIBUTE = "data-v-inspector-ignore";
+const OVERLAY_SELECTOR = "#vue-inspector-container";
+function getRuntime() {
+  return typeof window === "undefined" ? void 0 : window.__VUE_INSPECTOR__;
+}
+function isAdapterOwned(element) {
+  return element.hasAttribute(IGNORE_ATTRIBUTE) || Boolean(element.closest(OVERLAY_SELECTOR));
+}
+function getMarkerData(element) {
+  const vnodeData = element.__vnode?.props?.[VNODE_SOURCE_KEY];
+  if (vnodeData) return vnodeData;
+  const ctxVNode = element.__vnode?.ctx?.vnode;
+  if (ctxVNode?.el === element) {
+    const ctxData = ctxVNode.props?.[VNODE_SOURCE_KEY];
+    if (ctxData) return ctxData;
+  }
+  const vueInstance = element.__vueParentComponent;
+  let currentParent = vueInstance?.parent;
+  while (currentParent) {
+    if (currentParent.vnode?.el === element) {
+      const parentData = currentParent.vnode.props?.[VNODE_SOURCE_KEY];
+      if (parentData) return parentData;
+    }
+    currentParent = currentParent.parent;
+  }
+  return element.getAttribute(SOURCE_LOCATION_ATTRIBUTE) ?? void 0;
+}
+function resolveFromMarker(element) {
+  const data = getMarkerData(element);
+  return data ? (0, import_types.parseSourceLocation)(data) : null;
+}
+function resolveFromVueInstance(element) {
+  const vue3Instance = element.__vueParentComponent;
+  if (vue3Instance) {
+    let current = vue3Instance;
+    while (current) {
+      const file = current.type?.__file || current.vnode?.type?.__file;
+      if (file) {
+        return { file, line: null, column: null };
+      }
+      current = current.parent;
+    }
+  }
+  const vue2Instance = element.__vue__;
+  if (vue2Instance) {
+    let current = vue2Instance;
+    while (current) {
+      const file = current.$options?.__file;
+      if (file) {
+        return { file, line: null, column: null };
+      }
+      current = current.$parent;
+    }
+  }
+  return null;
+}
+function mergeSourceLocations(markerLocation, instanceLocation) {
+  if (!markerLocation?.file && !instanceLocation?.file) return null;
+  if (markerLocation?.file && instanceLocation?.file) {
+    const isNodeModules = (path) => path.includes("node_modules");
+    if (!isNodeModules(markerLocation.file)) return markerLocation;
+    if (!isNodeModules(instanceLocation.file)) return instanceLocation;
+    return markerLocation;
+  }
+  return markerLocation?.file ? markerLocation : instanceLocation;
+}
+let clickHandler = null;
+const vueInspectorAdapter = {
+  id: import_constants.INSPECTOR_ADAPTER_IDS.vue,
+  label: "Vue Inspector",
+  ignoreSelectors: [OVERLAY_SELECTOR],
+  ignoreAttributes: [IGNORE_ATTRIBUTE],
+  isAvailable() {
+    return Boolean(getRuntime());
+  },
+  resolveSourceLocation(element) {
+    let current = element;
+    let markerLocation = null;
+    let instanceLocation = null;
+    while (current && !(markerLocation && instanceLocation)) {
+      if (!isAdapterOwned(current)) {
+        markerLocation ?? (markerLocation = resolveFromMarker(current));
+        instanceLocation ?? (instanceLocation = resolveFromVueInstance(current));
+      }
+      current = current.parentElement;
+    }
+    return mergeSourceLocations(markerLocation, instanceLocation);
+  },
+  onElementClick(handler) {
+    clickHandler = handler;
+    const runtime = getRuntime();
+    if (!runtime || runtime.__aipanel_hooked) return;
+    const originalHandleClick = runtime.handleClick.bind(runtime);
+    runtime.handleClick = (event) => {
+      const element = event.target instanceof Element ? event.target : null;
+      if (clickHandler?.(element, event)) {
+        event.preventDefault();
+        event.stopPropagation();
+        return;
+      }
+      originalHandleClick(event);
+    };
+    runtime.__aipanel_hooked = true;
+  },
+  setEnabled(enabled) {
+    const runtime = getRuntime();
+    if (!runtime) return;
+    if (enabled) runtime.enable();
+    else runtime.disable();
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  vueInspectorAdapter
+});

package/lib/common/inspector/vue.d.ts

@@ -0,0 +1,20 @@
+import { type InspectorAdapter } from "./types";
+/** unplugin-vue-inspector 暴露到页面的运行时控制对象 */
+interface VueInspectorRuntime {
+    handleClick: (e: MouseEvent) => void;
+    enable: () => void;
+    disable: () => void;
+    /** AIPanel 已接管 handleClick 的标记（幂等安装） */
+    __aipanel_hooked?: boolean;
+}
+declare global {
+    interface Window {
+        __VUE_INSPECTOR__?: VueInspectorRuntime;
+    }
+}
+/**
+ * Vue 适配器：复用 unplugin-vue-inspector 注入的运行时与源码坐标标记，
+ * 在宿主选择模式下接管点击、解析元素源码位置。
+ */
+export declare const vueInspectorAdapter: InspectorAdapter;
+export {};

package/lib/common/types.d.ts

@@ -113,6 +113,18 @@ export interface PageContext {
  * 服务启动任务状态
  */
 export type ServiceStartupTask = "checking_provider" | "allocating_port" | "preparing_runtime" | "starting_web" | "waiting_web_ready" | "starting_proxy" | "warming_up_chrome" | "creating_session" | "provider_not_installed" | "web_start_timeout" | "proxy_start_failed" | "session_creation_failed" | "chrome_mcp_failed" | "ready";
+/**
+ * 服务启动任务状态载荷
+ * currentTask / SSE TASK_UPDATE / STATUS_SYNC 共用同一形态（单一来源）
+ */
+export interface ServiceTaskState {
+    /** 当前任务 */
+    task: ServiceStartupTask;
+    /** 失败原因类型（如 ChromeMcpWarmupErrorType） */
+    errorType?: string;
+    /** 失败原因文案 */
+    errorMessage?: string;
+}
 /**
  * 服务启动任务状态映射
  */

package/lib/index.cjs

@@ -15,6 +15,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var lib_exports = {};
 module.exports = __toCommonJS(lib_exports);
 __reExport(lib_exports, require("./common/constants.cjs"), module.exports);
+__reExport(lib_exports, require("./common/inspector/index.cjs"), module.exports);
 __reExport(lib_exports, require("./common/logger-core.cjs"), module.exports);
 __reExport(lib_exports, require("./common/options.cjs"), module.exports);
 __reExport(lib_exports, require("./common/provider.cjs"), module.exports);
@@ -23,6 +24,7 @@ __reExport(lib_exports, require("./common/utils.cjs"), module.exports);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ...require("./common/constants.cjs"),
+  ...require("./common/inspector/index.cjs"),
   ...require("./common/logger-core.cjs"),
   ...require("./common/options.cjs"),
   ...require("./common/provider.cjs"),

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./common/constants";
+export * from "./common/inspector";
 export * from "./common/logger-core";
 export * from "./common/options";
 export * from "./common/provider";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipanel/core",
-  "version": "1.2.19",
+  "version": "1.2.20",
   "type": "module",
   "sideEffects": false,
   "main": "lib/index.cjs",
@@ -37,6 +37,7 @@
   "scripts": {
     "build": "pagoda-cli build",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "typecheck": "tsc -p tsconfig.declaration.json --noEmit"
   }
 }