@proteus-vue/devtools 0.1.0

package/dist/plugins/network.d.ts

@@ -0,0 +1,2 @@
+import type { DevToolsPlugin } from '../plugins';
+export declare function createNetworkPlugin(): DevToolsPlugin;

package/dist/plugins.d.ts

@@ -0,0 +1,64 @@
+import type { TraceEvent } from '@proteus-vue/devtools-runtime';
+export interface DevToolsPlugin {
+    name: string;
+    version: string;
+    /** 依赖插件（激活拓扑排序；循环依赖 → activate 报错并给出环路径） */
+    peerDependencies?: string[];
+    setup(ctx: PluginContext): void | Promise<void>;
+}
+export interface PluginBus {
+    /** 订阅事件流；回调抛错 → 自动卸载 + 插件标记 crashed（核心不崩） */
+    on(cb: (e: TraceEvent) => void): () => void;
+}
+export interface PanelAPI {
+    /** 注册自定义视图（侧栏导航项 + 内容容器）；render 由面板 16ms 节流 rerender 调用 */
+    addView(id: string, opts: {
+        label: string;
+        icon?: string;
+        render: (container: HTMLElement) => void;
+    }): void;
+}
+export interface CommandRegistry {
+    register(id: string, run: () => void): void;
+    run(id: string): void;
+    /** 已注册命令 id 列表（命令面板展示用） */
+    list(): string[];
+}
+export interface KVStorage {
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown): void;
+}
+export interface PluginContext {
+    name: string;
+    bus: PluginBus;
+    panel: PanelAPI;
+    commands: CommandRegistry;
+    storage: KVStorage;
+}
+export type PluginStatus = 'registered' | 'active' | 'crashed';
+export interface PluginEntry {
+    name: string;
+    version: string;
+    status: PluginStatus;
+    error?: string;
+}
+/** 内存 KV（缺省存储；业务可注入 localStorage/IndexedDB 持久化） */
+export declare function createMemoryStorage(): KVStorage;
+export declare function createCommandRegistry(): CommandRegistry;
+/**
+ * 拓扑排序（Kahn）+ 循环依赖检测：按 peerDependencies 求激活顺序。
+ * 存在环 → 返回剩余节点的依赖环路径（用于报错提示）；无环 → cycle = null。
+ */
+export declare function resolveActivationOrder(plugins: DevToolsPlugin[]): {
+    order: string[];
+    cycle: string[] | null;
+};
+export interface PluginRegistry {
+    register(plugin: DevToolsPlugin): void;
+    unregister(name: string): void;
+    /** 拓扑序激活全部已注册插件（含依赖先激活）；插件崩溃不影响其余 */
+    activateAll(ctx: (plugin: DevToolsPlugin) => PluginContext): Promise<PluginEntry[]>;
+    list(): PluginEntry[];
+    get(name: string): DevToolsPlugin | undefined;
+}
+export declare function createPluginRegistry(initial?: DevToolsPlugin[]): PluginRegistry;

package/dist/session-io.d.ts

@@ -0,0 +1,35 @@
+import type { TraceEvent } from '@proteus-vue/devtools-runtime';
+import type { StoreStepIO, StoreRestoreEntry } from './snapshot-io';
+import type { DeviceInfo } from './views/device';
+export interface SessionBundle {
+    kind: 'proteus-session';
+    version: 1;
+    exportedAt: number;
+    meta: {
+        eventCount: number;
+        platform?: string;
+        userAgent?: string;
+    };
+    /** 可重放事件日志（重建 timeline/flame/errors/router-nav/store/component 聚合的唯一真相源） */
+    events: TraceEvent[];
+    /** 设备面板数据（环境/能力/内存基线） */
+    device?: DeviceInfo;
+    /** store 最新快照 + 步骤（应用侧恢复用；与快照导入同形态） */
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}
+export interface ParsedSession {
+    events: TraceEvent[];
+    device?: DeviceInfo;
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}
+/** 序列化会话（面板导出：事件日志 + 设备 + store 快照） */
+export declare function serializeSession(input: {
+    events: TraceEvent[];
+    device?: DeviceInfo;
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}): string;
+/** 解析并校验会话（非法 → null；坏事件行过滤保留合法行） */
+export declare function parseSession(json: string): ParsedSession | null;

package/dist/snapshot-io.d.ts

@@ -0,0 +1,37 @@
+export interface StoreRestoreEntry {
+    id: string;
+    state: Record<string, unknown>;
+}
+export interface StoreStepIO {
+    index: number;
+    storeId: string;
+    type: 'patch' | 'action';
+    name: string;
+    payload: unknown;
+    timestamp: number;
+}
+export interface StoreSnapshotIO {
+    kind: 'proteus-store-snapshot';
+    version: 1;
+    exportedAt: number;
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}
+export interface ParsedStoreSnapshot {
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}
+/** 敏感键检测结果（导出二次确认用；对齐 TraceBus 脱敏键规则） */
+export interface SensitiveKeyHit {
+    storeId: string;
+    keys: string[];
+}
+/** 递归扫描 state 树命中的敏感键（嵌套对象/数组；★M10 权限最小化 M7.3——导出前列出将导出的敏感字段） */
+export declare function findSensitiveKeys(stores: StoreRestoreEntry[]): SensitiveKeyHit[];
+/** 序列化快照（面板导出 / 测试 roundtrip） */
+export declare function serializeStoreSnapshot(input: {
+    stores: StoreRestoreEntry[];
+    steps: StoreStepIO[];
+}): string;
+/** 解析并校验快照 JSON（非法 → null） */
+export declare function parseStoreSnapshot(json: string): ParsedStoreSnapshot | null;

package/dist/source.d.ts

@@ -0,0 +1,22 @@
+import type { TraceEvent } from '@proteus-vue/devtools-runtime';
+import type { TraceBus } from '@proteus-vue/devtools-runtime';
+export interface DevtoolsSource {
+    /** 订阅事件流，返回取消函数 */
+    onEvent(cb: (e: TraceEvent) => void): () => void;
+    /** 订阅连接状态（可选）：WS 源连上即通知——面板「已连接」不再等首个事件（避免「连上了但暂无事件」误显示连接中） */
+    onStatus?(cb: (s: DevtoolsSourceStatus) => void): () => void;
+    /** 应用信息（Proteus.appInfo：pages/依赖图数据源；WS 源请求缓存，TraceBus 源缺省） */
+    appInfo?(): unknown;
+    /** ★M8 设备信息（Proteus.deviceInfo：环境/能力数据源；WS 源请求缓存，TraceBus 源缺省） */
+    deviceInfo?(): unknown;
+    /** ★G-43 B4 所有权图（Proteus.ownership：视图数据源；WS 源请求缓存，TraceBus 源缺省） */
+    ownership?(): unknown;
+    /** ★远程命令下发（WS 源：面板 → relay → 应用侧执行；如 Proteus.restoreStores 时间旅行恢复） */
+    sendCommand?(method: string, params?: Record<string, unknown>): void;
+    close(): void;
+}
+export type DevtoolsSourceStatus = 'connecting' | 'connected' | 'closed';
+/** TraceBus 直连源：进程内 TraceBus 事件 → DevtoolsSource（Web 端运行时接入用） */
+export declare function createTraceBusSource(bus: TraceBus): DevtoolsSource;
+/** WS 数据源：连接 dev server → Proteus.enable → 接收 Proteus.event 重组 TraceEvent（断线 1s 重连） */
+export declare function createDevtoolsWsSource(url: string, createSocket?: (url: string) => WebSocket): DevtoolsSource;

package/dist/tooltip.d.ts

@@ -0,0 +1,21 @@
+export interface TooltipData {
+    title: string;
+    /** 详情行（如 耗时 / 时间戳 / 阶段） */
+    lines: string[];
+}
+export declare function attachTip(el: HTMLElement, data: TooltipData): void;
+export declare function resolveTipData(target: HTMLElement): TooltipData | null;
+export interface TooltipLayer {
+    /** 显示浮层（position 相对 viewport） */
+    show(data: TooltipData, x: number, y: number): void;
+    hide(): void;
+    /** 销毁：从 document.body 移除浮层元素（面板 destroy 时调用） */
+    dispose(): void;
+    readonly visible: boolean;
+}
+export declare function createTooltipLayer(): TooltipLayer;
+/**
+ * 给容器绑定 tooltip：元素带 `data-tip` 且 resolve 返回数据 → hover 显示。
+ * 返回解绑函数。resolve 返回 null → 不显示（但隐藏当前）。
+ */
+export declare function bindTooltip(root: HTMLElement, layer: TooltipLayer, resolve: (target: HTMLElement) => TooltipData | null): () => void;

package/dist/views/components.d.ts

@@ -0,0 +1,26 @@
+import type { DomTreeNode } from '../component-trace';
+export interface ComponentNodeData {
+    id: number;
+    name: string;
+    parentId?: number;
+    /** 挂载时间戳 */
+    ts: number;
+    /** 同 id 重复挂载计数（组件复用场景） */
+    count: number;
+    /** mount 时刻 props 快照（serializeState 序列化，JSON-safe） */
+    props?: unknown;
+    /** mount 时刻 state 快照（options data / setupState） */
+    state?: unknown;
+}
+export interface ComponentsViewData {
+    nodes: ComponentNodeData[];
+    /** 选中组件 id（详情面板展示；缺省不选中） */
+    selectedId?: number;
+    /** ★P1.5：选中组件的渲染元素 DOM 树（component.inspect 事件下发） */
+    dom?: DomTreeNode;
+}
+export interface ComponentsViewHooks {
+    /** 选中组件 → 页面元素高亮（install 侧 scrollIntoView + flash；同 id 再点由调用方取消） */
+    onSelect?: (id: number) => void;
+}
+export declare function renderComponents(container: HTMLElement, data: ComponentsViewData, hooks?: ComponentsViewHooks): void;

package/dist/views/device.d.ts

@@ -0,0 +1,43 @@
+export interface DeviceScreenInfo {
+    dpr: number;
+    width: number;
+    height: number;
+    /** 安全区（CSS env(safe-area-inset-*)；刘海屏；无则 undefined） */
+    safeTop?: number;
+    safeBottom?: number;
+}
+export interface DeviceMemoryInfo {
+    jsHeapLimit: number;
+    totalJSHeapSize: number;
+    usedJSHeapSize: number;
+}
+export interface DeviceCapabilityInfo {
+    capability: string;
+    platform: string;
+    priority: number;
+    required: boolean;
+    fallback?: string;
+    supported: boolean;
+    runsInWorklet?: boolean;
+    platforms: string[];
+}
+export interface DeviceInfo {
+    platform: string;
+    userAgent?: string;
+    /** 基础库版本（小程序；web 缺省） */
+    libVersion?: string;
+    screen?: DeviceScreenInfo;
+    memory?: DeviceMemoryInfo;
+    capabilities: DeviceCapabilityInfo[];
+}
+export interface DeviceMemorySample {
+    t: number;
+    used: number;
+    total: number;
+    limit: number;
+}
+export interface DeviceViewData {
+    info?: DeviceInfo;
+    memory: DeviceMemorySample[];
+}
+export declare function renderDevice(container: HTMLElement, data: DeviceViewData): void;

package/dist/views/errors.d.ts

@@ -0,0 +1,5 @@
+import type { RootCauseReport } from '@proteus-vue/devtools-runtime';
+export interface ErrorsViewData {
+    reports: RootCauseReport[];
+}
+export declare function renderErrors(container: HTMLElement, data: ErrorsViewData): void;

package/dist/views/flamegraph.d.ts

@@ -0,0 +1,20 @@
+import type { FlameNode, FlameCompareEntry } from '@proteus-vue/devtools-runtime';
+export interface FlamegraphViewData {
+    nodes: FlameNode[];
+    /** 对比数据（与 baseline 录制 diff；缺省单录制无高亮） */
+    compare?: FlameCompareEntry[];
+    /** ★聚焦（zoom）：渲染该节点子树；缺省渲染全部根 */
+    focus?: FlameNode;
+    /** 面包屑（焦点祖先链，含焦点自身） */
+    breadcrumb?: Array<{
+        id: string;
+        name: string;
+    }>;
+}
+export interface FlamegraphViewHooks {
+    /** 点击块 → 聚焦该节点（zoom 到其子树） */
+    onFocus?: (id: string) => void;
+    /** 返回上级（面包屑最后一项 / 退出 zoom 到根） */
+    onFocusUp?: () => void;
+}
+export declare function renderFlamegraph(container: HTMLElement, data: FlamegraphViewData, hooks?: FlamegraphViewHooks): void;

package/dist/views/graph.d.ts

@@ -0,0 +1,5 @@
+import type { PageRouteData } from './pages';
+export interface GraphViewData {
+    routes: PageRouteData[];
+}
+export declare function renderGraph(container: HTMLElement, data: GraphViewData): void;

package/dist/views/inspector.d.ts

@@ -0,0 +1,9 @@
+/** 值编辑钩子（state 视图双向调试；components 视图不传则只读） */
+export interface InspectorEditHooks {
+    /** 原始值编辑提交（path 相对渲染根；非法输入不回调） */
+    onEdit?: (path: Array<string | number>, value: unknown) => void;
+}
+/** 单行摘要（object/array 折叠态显示） */
+export declare function summarize(value: unknown): string;
+/** 递归渲染 key-value 树（可折叠：object/array 行点击展开/收起；★path + hooks 支持原始值编辑双向调试） */
+export declare function renderKeyValue(container: HTMLElement, key: string, value: unknown, depth: number, initiallyOpen?: boolean, path?: Array<string | number>, hooks?: InspectorEditHooks): void;

package/dist/views/ownership.d.ts

@@ -0,0 +1,4 @@
+import type { OwnershipViewData } from '../ownership-info';
+export type { OwnershipViewData };
+/** ★G-43 B4：所有权视图渲染（纯数据 → DOM；空数据 → 空态提示） */
+export declare function renderOwnership(container: HTMLElement, data: OwnershipViewData | undefined): void;

package/dist/views/pages.d.ts

@@ -0,0 +1,18 @@
+export interface PageRouteData {
+    name: string;
+    path: string;
+    parent?: string;
+    meta?: {
+        title?: string;
+        isTab?: boolean;
+    };
+    subPackage?: string;
+}
+export interface PagesViewData {
+    routes: PageRouteData[];
+    /** 当前页面栈（MP 真实栈；Web 恒 1 项） */
+    stack?: Array<{
+        route?: string;
+    }>;
+}
+export declare function renderPages(container: HTMLElement, data: PagesViewData): void;

package/dist/views/route.d.ts

@@ -0,0 +1,5 @@
+import type { NavRecord } from '@proteus-vue/devtools-runtime';
+export interface RouteViewData {
+    records: NavRecord[];
+}
+export declare function renderRoute(container: HTMLElement, data: RouteViewData): void;

package/dist/views/state.d.ts

@@ -0,0 +1,26 @@
+import type { StateSnapshot, PatchStep } from '@proteus-vue/devtools-runtime';
+export interface StateViewHooks {
+    /** 时间旅行回放到第 index 步（index = -1 表示初始快照） */
+    onTimeTravel?: (index: number) => void;
+    /** 选中 store（Pinia 面板布局：单选详情） */
+    onSelectStore?: (id: string) => void;
+    /** 导出快照（面板侧 Blob 下载） */
+    onExport?: () => void;
+    /** 导入快照 JSON（view 读文件 → 面板解析校验 + 数据重建 + 应用） */
+    onImport?: (json: string) => void;
+    /** ★M11 可观测性（M8.2）：导出 SessionBundle（可重放事件日志 + 设备 + store 快照） */
+    onExportSession?: () => void;
+    /** ★M11 可观测性（M8.2）：导入 SessionBundle（完整还原另一环境） */
+    onImportSession?: (json: string) => void;
+    /** ★双向调试：值编辑提交（点值改 → 应用侧 $patch 写回真实状态） */
+    onEditValue?: (storeId: string, path: Array<string | number>, value: unknown) => void;
+}
+export interface StateViewData {
+    snapshot: StateSnapshot;
+    steps: PatchStep[];
+    /** 当前选中 store（缺省第一个有快照的 store） */
+    selectedStore?: string;
+    /** ★当前时间旅行回放位置（rerender 后滑块保持；缺省最新） */
+    travelIndex?: number;
+}
+export declare function renderState(container: HTMLElement, data: StateViewData, hooks?: StateViewHooks): void;

package/dist/views/timeline-interaction.d.ts

@@ -0,0 +1,12 @@
+import type { TimelineSpan } from '@proteus-vue/devtools-runtime';
+import type { TimelineWindow } from './timeline';
+export interface TimelineZoomOptions {
+    /** 窗口变更回调（panel 触发节流 rerender） */
+    onWindowChange?: (w: TimelineWindow) => void;
+}
+export interface TimelineZoom {
+    /** 当前窗口（未交互过 → null，panel 传 undefined 让渲染函数自算全窗） */
+    getWindow(): TimelineWindow | null;
+    destroy(): void;
+}
+export declare function createTimelineZoom(container: HTMLElement, getSpans: () => TimelineSpan[], opts?: TimelineZoomOptions): TimelineZoom;

package/dist/views/timeline.d.ts

@@ -0,0 +1,16 @@
+import type { TimelineSpan } from '@proteus-vue/devtools-runtime';
+export interface TimelineWindow {
+    start: number;
+    end: number;
+}
+export interface TimelineViewData {
+    spans: TimelineSpan[];
+    /** 时间轴窗口（缺省自动取 min start ~ max end） */
+    window?: TimelineWindow;
+    /** 虚拟滚动（万级 span 分块渲染）：仅渲染视口内泳道；容器由调用方设为 overflow-y 滚动 */
+    virtual?: {
+        scrollTop: number;
+        viewHeight: number;
+    };
+}
+export declare function renderTimeline(container: HTMLElement, data: TimelineViewData): void;

package/dist/vue-devtools.d.ts

@@ -0,0 +1,133 @@
+import type { DevtoolsSource } from './source';
+/** @vue/devtools-api DevtoolsApi 的结构类型（只取 Timeline 能力面） */
+export interface VueDevtoolsApiLike {
+    addTimelineLayer(options: {
+        id: string;
+        label: string;
+        color?: number;
+    }): void;
+    addTimelineEvent(options: {
+        layerId: string;
+        event: unknown;
+    }): void;
+}
+export interface VueDevtoolsTimelineOptions {
+    /** Proteus 事件源（TraceBus 直连 / WS-CDP / mock） */
+    source: DevtoolsSource;
+    /** layer 颜色（Vue DevTools Timeline 色板，缺省紫蓝） */
+    color?: number;
+}
+export interface VueDevtoolsTimeline {
+    /** 卸载：取消事件订阅 */
+    dispose(): void;
+    /** 已注册的 layer id */
+    readonly layerId: string;
+}
+/**
+ * 接入 Vue 官方 DevTools：注册 'proteus' Timeline layer，把事件流推送为 Timeline 事件。
+ * 用法（应用侧）：setupDevtoolsPlugin({ id: 'proteus', label: 'Proteus', app }, (api) => {
+ *   installProteusTimeline(api, { source })
+ * })
+ */
+export declare function installProteusTimeline(api: VueDevtoolsApiLike, options: VueDevtoolsTimelineOptions): VueDevtoolsTimeline;
+/** 自定义 Inspector 所需的 @vue/devtools-api 形状（结构类型注入，可 mock 单测）
+ * ★state 是「分组名 → 状态行数组」对象（CustomInspectorState：`{ 分组: [{key, value}] }`）——
+ *   传数组会让 Vue DevTools 渲染不出分组详情（2026-09 实测根因） */
+export interface VueDevtoolsInspectorApiLike {
+    addInspector(options: {
+        id: string;
+        label: string;
+        icon?: string;
+    }): void;
+    on: {
+        getInspectorTree(cb: (payload: {
+            inspectorId: string;
+            rootNodes?: unknown[];
+        }) => void): void;
+        getInspectorState(cb: (payload: {
+            inspectorId: string;
+            nodeId: string;
+            state?: Record<string, Array<{
+                key: string;
+                value: unknown;
+            }>>;
+        }) => void): void;
+        editInspectorState(cb: (payload: {
+            inspectorId: string;
+            nodeId: string;
+            path: string[];
+            state: {
+                value: unknown;
+            };
+        }) => void): void;
+    };
+}
+export interface ProteusInspectorsOptions {
+    /** 应用配置读取（缺省空对象；业务侧传 getConfig） */
+    getConfig?: () => Record<string, unknown>;
+    /** 配置更新（编辑回写——Web 端响应式更新白给；缺省 no-op） */
+    setConfig?: (patch: Record<string, unknown>) => void;
+    /**
+     * style-safety 拦截记录读取（G-31 runtime guard.records()；提供则注册 proteus-style-safety inspector）
+     * 对齐 vue-devtools-plan §3：`p.state = [{ key: 'rejected', value: getRejectedRecords() }]`
+     */
+    getStyleSafetyRecords?: () => Array<{
+        prop: string;
+        value: unknown;
+        reason: string;
+        ts: number;
+    }>;
+    /**
+     * 路由表（父引用嵌套树 → proteus-router Inspector：Vue DevTools 内置 Router 面板只认 vue-router，
+     * 我们用自己的路由 → 自定义 Inspector 展示路由树 + 详情）
+     */
+    pages?: {
+        routes: Array<{
+            name: string;
+            path: string;
+            parent?: string;
+            subPackage?: string;
+            meta?: Record<string, unknown>;
+        }>;
+    };
+    /**
+     * 导航记录（动态数据 → proteus-router Inspector 的「导航记录」节点：当前路由 + 最近导航历史，
+     * 对齐 vue-router 面板的 Router 记录形态；由 install 侧聚合 router 事件提供）
+     * 记录含完整导航状态：from/to/耗时/时间/traceId/守卫链
+     */
+    getRouterState?: () => {
+        currentRoute?: string;
+        records: Array<{
+            from: string;
+            to: string;
+            query?: Record<string, string>;
+            durationMs: number;
+            timestamp: number;
+            traceId?: string;
+            guards: Array<{
+                name: string;
+                result: 'next' | 'cancel' | 'redirect' | 'error';
+            }>;
+        }>;
+    };
+}
+export interface ProteusInspectors {
+    dispose(): void;
+}
+export declare const PROTEUS_DEVTOOLS_PLUGIN_DESCRIPTOR: {
+    readonly id: "proteus";
+    readonly label: "Proteus";
+    /** ★触发 fallback 的占位 logo（根相对路径：扩展/独立/dev server 下 404 或图片解码失败 → img error）
+     * 不能传 undefined（三个 inspector 全默认图标），也不能传真实图片 URL（会直接显示图片而非字典图标） */
+    readonly logo: "/__proteus-inspector-icons__.svg";
+};
+/**
+ * 注册自定义 Inspector（vue-devtools-plan §3 可落地项）：
+ *   `proteus-app-config`——App Config 当前生效值 + 编辑回写（对齐规划 §6 双向调试的 Web 形态）
+ *   `proteus-style-safety`——运行时拦截记录（G-31 guard.records()，需提供 getStyleSafetyRecords）
+ *   `proteus-router`——路由嵌套树 + 详情（★Vue DevTools 内置 Router 面板只认 vue-router，自研路由需自定义 Inspector）
+ * 用法（应用侧）：setupDevtoolsPlugin({ id: 'proteus', label: 'Proteus', app }, (api) => {
+ *   installProteusInspectors(api, { getConfig, setConfig, getStyleSafetyRecords, pages })
+ * })
+ */
+export declare function installProteusInspectors(api: VueDevtoolsInspectorApiLike, options?: ProteusInspectorsOptions): ProteusInspectors;

package/dist/ws-bridge.d.ts

@@ -0,0 +1,21 @@
+import type { TraceBus } from '@proteus-vue/devtools-runtime';
+export interface TraceBusWsBridgeOptions {
+    /** WS 地址（如 ws://host/proteus-source——由 devtoolsRelayPlugin 提供端点） */
+    url: string;
+    /** Proteus.appInfo 响应（面板 pages/依赖图数据；缺省空对象） */
+    appInfo?: () => unknown;
+    /** ★M8 设备面板：Proteus.deviceInfo 响应（环境/能力上报；缺省空对象） */
+    deviceInfo?: () => unknown;
+    /** ★G-43 B4 所有权面板：Proteus.ownership 响应（视图数据上报；缺省空对象） */
+    ownership?: () => unknown;
+    /** ★远程时间旅行：面板 Proteus.restoreStores 命令 → 应用侧恢复（install 传 pinia.$patch 闭包） */
+    onRestoreStores?: (stores: Array<{
+        id: string;
+        state: Record<string, unknown>;
+    }>) => void;
+}
+export interface TraceBusWsBridge {
+    close(): void;
+}
+/** 创建 TraceBus → WS 桥（业务侧 installProteusDevtools remote 选项内部使用；也可独立接入） */
+export declare function createTraceBusWsBridge(bus: TraceBus, options: TraceBusWsBridgeOptions): TraceBusWsBridge;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@proteus-vue/devtools",
+  "version": "0.1.0",
+  "description": "Proteus DevTools 面板（devtools-plan UI 层）：十视图（时间轴/火焰图/状态·时间旅行·值编辑/路由/根因/组件/页面/依赖图/设备/所有权）+ 一键接入 + Vue DevTools 插件（Timeline/Inspectors）+ 开放数据源（WS/CDP 协议）——浏览器端 dev 工具，不随业务产物发布",
+  "type": "module",
+  "license": "Apache-2.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./panel": "./panel.html",
+    "./style": "./style.css",
+    "./style.css": "./style.css",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "panel.html",
+    "style.css",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --platform=browser --outfile=dist/index.js --external:@proteus-vue/capabilities --external:@proteus-vue/devtools-runtime --external:@proteus-vue/render-backend --external:@vue/devtools-api && esbuild src/index.ts --bundle --format=iife --global-name=ProteusDevtools --platform=browser --outfile=dist/panel.js"
+  },
+  "dependencies": {
+    "@proteus-vue/capabilities": "0.1.0",
+    "@proteus-vue/devtools-runtime": "0.1.0",
+    "@proteus-vue/render-backend": "0.1.0"
+  },
+  "peerDependencies": {
+    "@vue/devtools-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@vue/devtools-api": "^8.0.0",
+    "pinia": "^4.0.0",
+    "vue": "^3.4.0"
+  }
+}

package/panel.html

@@ -0,0 +1,26 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Proteus DevTools</title>
+  <!-- Vue DevTools 质感主题（style.css；file:// 双击可直接打开——普通样式表无 CORS 限制） -->
+  <link rel="stylesheet" href="./style.css" />
+</head>
+<body class="pd-body">
+  <div id="proteus-devtools"></div>
+  <!-- ★IIFE bundle：file:// 双击可直接打开（module 脚本在 file:// 下被浏览器 CORS 拦截 → 黑屏） -->
+  <script src="./dist/panel.js"></script>
+  <script>
+    // 数据源：?ws= 覆盖连接地址
+    //   ① dev-mp HMR/CDP 通道：缺省 ws://127.0.0.1:5174/（小程序开发；PROTEUS_DEVTOOLS_URL 可覆盖）
+    //   ② ★Web 远程查看（移动端/真机）：vite dev 起 devtoolsRelayPlugin 后，
+    //      连 ws://<vite-host>/proteus-panel——手机跑应用（installProteusDevtools remote: true 上行），电脑开本页查看
+    //   ③ /proteus-devtools 页面端点注入时把默认 WS 占位符替换为当前 host 的 ws://host/proteus-panel；
+    //      file:// 双击未注入时回退 5174（dev-mp 场景）
+    var url = new URLSearchParams(location.search).get('ws') || (typeof __PROTEUS_DEFAULT_WS__ === 'string' ? __PROTEUS_DEFAULT_WS__ : 'ws://127.0.0.1:5174/')
+    var source = ProteusDevtools.createDevtoolsWsSource(url)
+    ProteusDevtools.createDevtoolsPanel(document.getElementById('proteus-devtools'), { source: source })
+  </script>
+</body>
+</html>