@proteus-vue/devtools 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# @proteus-vue/devtools
+
+Proteus DevTools（devtools-plan **UI 层**）——把 TraceBus 事件流渲染成可交互调试面板。**浏览器端开发工具，不随业务产物发布**；数据层消费 `@proteus-vue/devtools-runtime`（六源 → TraceBus → **十视图**）。
+
+## 导出
+
+### 面板装配 / 数据源
+
+| API | 说明 |
+|-----|------|
+| `createDevtoolsPanel(root, options)` | **面板装配**：tab 布局（十视图）+ 数据层收集器 + 渲染节流；`show(view)` 切视图 / `exportSnapshot()/importSnapshot()` 快照 / `destroy()` 清理 |
+| `createDevtoolsWsSource(url, createSocket?)` | **WS 数据源**：连 relay（CDP 协议 `Proteus.enable/event/appInfo/deviceInfo`）→ 事件流重组 + 元数据缓存 + `sendCommand()` 下发；断线 1s 重连 + enable 未确认 2s 重发 |
+| `createTraceBusSource(bus)` | **TraceBus 直连源**：进程内事件流 → DevtoolsSource（Web 端接入用） |
+| `createTraceBusWsBridge(bus, options)` | **远程查看桥**：应用侧 TraceBus → WS（`/proteus-source`）上行 → 电脑端面板下行；处理 enable 回放 / appInfo / deviceInfo / restoreStores |
+
+### 一键接入（推荐）
+
+| API | 说明 |
+|-----|------|
+| `installProteusDevtools(app, options)` | **★一键接入**：TraceBus 单例 + Vue DevTools 插件（Timeline/Inspectors）+ store/组件追踪 + 本地面板浮动挂载（◈ 按钮，可拖拽记忆位置）+ 远程桥 + HMR 事件源，一行完成全部接线 |
+| `installProteusTimeline(api, options)` | 接入 Vue 官方 DevTools：注册 `proteus` Timeline layer（事件流推为 Vue DevTools Timeline） |
+| `installProteusInspectors(api, options)` | 接入 Vue 官方 DevTools：**Router / App Config / Style Safety** 三个自定义 Inspector |
+| `PROTEUS_DEVTOOLS_PLUGIN_DESCRIPTOR` | Vue DevTools 插件描述符（logo 占位 + 三 Inspector 图标：⚙️ settings / 🛡 gpp-good / 🛣 route） |
+| `installComponentTrace(app, bus)` / `buildDomTree(el)` | 组件树追踪（mount/unmount 事件 + 元素 registry）+ DOM 树构建（组件视图详情/页面高亮） |
+
+### 视图渲染（纯函数 data → DOM，jsdom 可单测）
+
+`renderTimeline` / `renderFlamegraph` / `renderState` / `renderRoute` / `renderErrors` / `renderComponents` / `renderPages` / `renderGraph` / `renderDevice` / `renderOwnership` + 配套类型。
+
+### 插件 / 工具
+
+| API | 说明 |
+|-----|------|
+| `createPluginRegistry / createMemoryStorage / createCommandRegistry / resolveActivationOrder` | **M9 插件宿主**：第三方视图/事件订阅/命令/持久化（激活拓扑序、循环依赖报错、崩溃隔离） |
+| `createNetworkPlugin` | 内置插件：API 瀑布增强 + 请求重放 |
+| `serializeStoreSnapshot / parseStoreSnapshot` | 状态快照导出/导入（JSON 校验重建） |
+| `createTooltipLayer / bindTooltip / attachTip / resolveTipData` | hover 浮层 |
+| `detectRuntimePlatform / detectBrowserVersion / detectMpLibVersion` | 设备信息采集纯函数（真实平台/基础库探测） |
+
+## 十视图
+
+| 视图 | 渲染内容 |
+|------|---------|
+| **timeline** | 按 source 泳道分组 + span 线段 + pending 标注 + wheel 缩放/拖拽平移/双击重置 + 虚拟滚动 |
+| **flamegraph** | **经典嵌套堆叠火焰图**（子块相对父定位 + source 八色）+ 合成「录制会话」根 + 点击聚焦 zoom + 面包屑 + 对比模式（±10% 回归红/优化绿） |
+| **state** | store 选择器 + inspector 树 + actions/patches 时间线 + 时间旅行滑块 + **★值编辑双向调试**（点值改 → `$patch` 写回真实状态） |
+| **route** | 导航链 + 守卫徽章（next 绿 / redirect 橙 / cancel·error 红）+ 耗时 |
+| **errors** | 根因卡片（attribution ⚑ + causedBy 链 + 影响范围 + 复现步骤） |
+| **components** | 组件树（props/state 快照 + count）+ 选中 → 页面元素高亮（scrollIntoView + 描边）+ DOM 树详情 |
+| **pages** | 当前页面栈 + 主包/分包路由清单（Proteus.appInfo 数据源） |
+| **graph** | 页面依赖图（appInfo 路由表 → 父子关系） |
+| **device** | ★M8 环境概览卡（平台/基础库/屏幕/JS 堆）+ 能力表（✅/❌ + required/fallback/worklet）+ 内存曲线（每秒采样） |
+| **ownership** | ★G-43 B4 所有权概要（alive/total/bytes）+ 四类告警（🔴 无主/⚠️ 泄漏路径含引用链/🟡 长期借用/跨页强引用/✅ 无异常）+ 资源树（owner 分组 + 📍 源码行 + 🟡 借用方）+ alloc/drop 时间线（配对 ↔ + 未配对 ⚠️ 高亮）——数据源 `createOwnershipTracer` / `Proteus.ownership` 远程命令 |
+
+## ★一键接入（Web 端，examples/main.ts 已示范）
+
+```ts
+import { installProteusDevtools } from '@proteus-vue/devtools'
+import { getProteusTraceBus } from '@proteus-vue/devtools-runtime'
+
+const traceBus = getProteusTraceBus()
+if (import.meta.env.DEV || __PROTEUS_DEBUG__) traceBus.setEnabled(true) // 门控：生产零开销
+
+installProteusDevtools(app, {
+  pinia,                       // → store 追踪 + 时间旅行 + 值编辑
+  getConfig, setConfig,        // → Vue DevTools App Config Inspector
+  styleGuard,                  // → Vue DevTools Style Safety Inspector
+  pages: { routes },           // → pages/依赖图面板
+  remote: true,                // → 远程查看桥（移动端/真机：电脑开面板看）
+  hmr: import.meta.hot,        // → HMR 事件（vite:update/full-reload/error → timeline）
+})
+```
+
+面板浮动按钮 **◈**（可拖拽、位置记忆）；remote 开启后电脑浏览器开 dev server 打印的 `http://localhost:5173/proteus-devtools` 查看。
+
+## ★后端开放 API（第三方接入自己的面板）
+
+`DevtoolsSource` 是统一数据源接口（**官方面板自身就是它的消费者**，对标 `@vue/devtools-api` 的 client 角色）：
+
+```ts
+const source = createDevtoolsWsSource('ws://host/proteus-panel') // 远程；进程内用 createTraceBusSource(bus)
+source.onEvent((e) => myTimeline.push(e))   // 自绘 UI，只用数据
+console.log(source.appInfo?.(), source.deviceInfo?.())           // 元数据查询
+source.sendCommand?.('Proteus.restoreStores', { stores })        // 命令下发（双向调试）
+```
+
+**零包依赖**：协议是明文 JSON WebSocket（`Proteus.enable/event/appInfo/deviceInfo/restoreStores`，relay 端点 `/proteus-source` + `/proteus-panel`）——第三方仅需 WebSocket + 几行 JSON。完整规范见 `docs/proteus-devtools-plan/15-open-api.md`，零依赖实现见 `examples/pages/devtools-open-api-demo.vue`。
+
+## 插件扩展（M9）
+
+第三方在官方面板里加自定义视图/泳道/命令（`DevToolsPlugin` + `PluginContext`：bus/panel/commands/storage）：
+
+```ts
+import { createDevtoolsPanel, createPluginRegistry } from '@proteus-vue/devtools'
+// options.plugins: [{ name, version, setup(ctx) { ctx.panel.addView('my', '我的视图', (el) => {...}) } }]
+```
+
+## 使用（独立面板）
+
+```html
+<script src="@proteus-vue/devtools/panel"></script> <!-- IIFE bundle：file:// 双击可直接打开 -->
+<script>
+  const source = ProteusDevtools.createDevtoolsWsSource('ws://127.0.0.1:5174/')
+  ProteusDevtools.createDevtoolsPanel(document.getElementById('root'), { source })
+</script>
+```
+
+dev 模式更推荐浏览器直接开 `http://localhost:5173/proteus-devtools`（devtoolsRelayPlugin 提供页面端点 + 注入默认 WS）。
+
+## 设计约束（对齐 plan 铁律）
+
+- **铁律 1**：UI 只消费事件流（TraceBus 唯一入口），不直接碰运行时
+- 双向写回经回调/命令（`onApplyState` / `sendCommand('Proteus.restoreStores')`）——本地 `$patch` + 远程 relay 双通道
+- 事件 payload 全程脱敏（password/token/authorization/idcard/phone）；生产构建零端点零开销

package/dist/component-trace.d.ts

@@ -0,0 +1,35 @@
+import type { App } from 'vue';
+/** component 事件总线（结构与 devtools-runtime TraceBus.emit 兼容；业务侧直接传 createTraceBus 实例） */
+export interface ComponentTraceBus {
+    emit(source: 'component', phase: 'point', name: string, payload?: unknown, traceId?: string): void;
+}
+/** 组件快照数据（props/state 序列化后——type tag 安全，JSON-safe） */
+export interface ComponentSnapshot {
+    props?: unknown;
+    state?: unknown;
+}
+/** DOM 树节点（选中组件时构建渲染元素树，事件流下发——远程面板同样可见） */
+export interface DomTreeNode {
+    tag: string;
+    id?: string;
+    cls?: string[];
+    children: DomTreeNode[];
+}
+/**
+ * 构建 DOM 元素树摘要（选中组件 → 渲染结构可视化）：tag/id/class + 子元素递归
+ * ★深度/数量上限防超大 payload（depth ≤ 4、children ≤ 20、class ≤ 10）
+ */
+export declare function buildDomTree(el: Element, depth?: number): DomTreeNode | null;
+export interface ComponentTraceHandle {
+    dispose(): void;
+    /** ★P1：按组件 id 取根 DOM 元素（页面高亮；fragment 取首个元素节点） */
+    getElement(id: number): HTMLElement | null;
+}
+/**
+ * 注入组件生命周期事件：
+ *   component.mount   payload { id, name, parentId, props?, state? }   traceId comp-<id>（★props/state 为 mount 时刻快照）
+ *   component.unmount payload { id }                    （面板移除节点）
+ * 实例 id 经 WeakMap 稳定（复用组件挂载 id 不变 → 面板计数 ×N）
+ * ★app.mixin 无卸载 API——安装后随 app 生命周期；返回 handle（dispose no-op + getElement registry）
+ */
+export declare function installComponentTrace(app: App, bus: ComponentTraceBus): ComponentTraceHandle;

package/dist/device-info.d.ts

@@ -0,0 +1,5 @@
+export declare function detectRuntimePlatform(): 'web' | 'skyline' | 'app';
+/** web 基础库降级展示：浏览器内核版本（UA 解析；匹配不到 → undefined） */
+export declare function detectBrowserVersion(ua: string | undefined): string | undefined;
+/** 小程序基础库版本（wx SDKVersion；异常静默） */
+export declare function detectMpLibVersion(wxGlobal: unknown): string | undefined;

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+export { createDevtoolsPanel } from './panel';
+export type { DevtoolsPanel, DevtoolsPanelOptions } from './panel';
+export { createDevtoolsWsSource } from './source';
+export type { DevtoolsSource } from './source';
+export { createTraceBusSource } from './source';
+export { createTraceBusWsBridge } from './ws-bridge';
+export type { TraceBusWsBridge, TraceBusWsBridgeOptions } from './ws-bridge';
+export { installProteusTimeline, installProteusInspectors, PROTEUS_DEVTOOLS_PLUGIN_DESCRIPTOR } from './vue-devtools';
+export type { VueDevtoolsApiLike, VueDevtoolsTimelineOptions, VueDevtoolsTimeline, VueDevtoolsInspectorApiLike, ProteusInspectorsOptions, ProteusInspectors } from './vue-devtools';
+export { renderTimeline } from './views/timeline';
+export type { TimelineViewData, TimelineWindow } from './views/timeline';
+export { createTimelineZoom } from './views/timeline-interaction';
+export type { TimelineZoom, TimelineZoomOptions } from './views/timeline-interaction';
+export { renderFlamegraph } from './views/flamegraph';
+export type { FlamegraphViewData } from './views/flamegraph';
+export { renderState } from './views/state';
+export type { StateViewData, StateViewHooks } from './views/state';
+export { renderRoute } from './views/route';
+export type { RouteViewData } from './views/route';
+export { renderErrors } from './views/errors';
+export type { ErrorsViewData } from './views/errors';
+export { renderComponents } from './views/components';
+export type { ComponentsViewData, ComponentNodeData, ComponentsViewHooks } from './views/components';
+export { renderPages } from './views/pages';
+export type { PagesViewData, PageRouteData } from './views/pages';
+export { renderGraph } from './views/graph';
+export type { GraphViewData } from './views/graph';
+export { renderDevice } from './views/device';
+export type { DeviceInfo, DeviceViewData, DeviceMemorySample, DeviceCapabilityInfo, DeviceMemoryInfo, DeviceScreenInfo } from './views/device';
+export { renderOwnership } from './views/ownership';
+export { createOwnershipTracer } from './ownership-info';
+export type { OwnershipTracer, OwnershipTracerOptions, OwnershipViewData, OwnershipResourceItem } from './ownership-info';
+export { serializeStoreSnapshot, parseStoreSnapshot, findSensitiveKeys } from './snapshot-io';
+export type { StoreSnapshotIO, StoreRestoreEntry, StoreStepIO, ParsedStoreSnapshot, SensitiveKeyHit } from './snapshot-io';
+export { serializeSession, parseSession } from './session-io';
+export type { SessionBundle, ParsedSession } from './session-io';
+export { installComponentTrace } from './component-trace';
+export type { ComponentTraceBus, ComponentSnapshot, ComponentTraceHandle, DomTreeNode } from './component-trace';
+export { buildDomTree } from './component-trace';
+export { installProteusDevtools } from './install';
+export type { InstallDevtoolsOptions, InstalledDevtools, StyleGuardLike } from './install';
+export { detectRuntimePlatform, detectBrowserVersion, detectMpLibVersion } from './device-info';
+export { createTooltipLayer, bindTooltip, attachTip, resolveTipData } from './tooltip';
+export type { TooltipData, TooltipLayer } from './tooltip';
+export { createPluginRegistry, createMemoryStorage, createCommandRegistry, resolveActivationOrder } from './plugins';
+export type { DevToolsPlugin, PluginContext, PluginBus, PanelAPI, CommandRegistry, KVStorage, PluginEntry } from './plugins';
+export { createNetworkPlugin } from './plugins/network';