@proteus-vue/devtools 0.1.0

package/dist/install.d.ts

@@ -0,0 +1,76 @@
+import type { App } from 'vue';
+import type { TraceBus } from '@proteus-vue/devtools-runtime';
+import type { PagesViewData } from './views/pages';
+import type { OwnershipGraph, OwnershipHistory } from '@proteus-vue/render-backend';
+/** style-safety 守卫的结构类型（零硬依赖——@proteus-vue/style-safety 实例直接可传） */
+export interface StyleGuardLike {
+    records(): Array<{
+        prop: string;
+        value: unknown;
+        reason: string;
+        ts: number;
+    }>;
+}
+/** pinia 实例结构类型（createStoreTracer 消费 + onApplyState 状态恢复 + 面板创建补发快照） */
+export interface PiniaLike {
+    use(fn: (ctx: {
+        store: unknown;
+    }) => void): unknown;
+    _s: Map<string, {
+        $patch(state: Record<string, unknown>): void;
+        $state?: Record<string, unknown>;
+    }>;
+}
+/** vite import.meta.hot 结构类型（HMR 事件 → TraceBus；零硬依赖，业务侧传 import.meta.hot） */
+export interface HmrLike {
+    on(event: string, cb: (...args: unknown[]) => void): (() => void) | void;
+}
+export interface InstallDevtoolsOptions {
+    /** pinia 实例（提供 → store 变更追踪：面板 state 视图 + Pinia Inspector 原生） */
+    pinia?: PiniaLike;
+    /** app-config 读取（App Config Inspector 数据源；缺省空对象） */
+    getConfig?: () => Record<string, unknown>;
+    /** app-config 更新（编辑回写双向调试） */
+    setConfig?: (patch: Record<string, unknown>) => void;
+    /** style-safety 守卫（提供 → Style Safety Inspector 拦截记录数据源） */
+    styleGuard?: StyleGuardLike;
+    /** 本地面板 pages 数据（路由表 + 页面栈 → pages/依赖图面板） */
+    pages?: PagesViewData;
+    /** 是否挂载本地面板浮动窗口（缺省 true；仅挂载一次——重复调用复用） */
+    mount?: boolean;
+    /** vite HMR 句柄（传 import.meta.hot）：热更新事件 → TraceBus（timeline 显示 vite:update/full-reload/error 记录） */
+    hmr?: HmrLike;
+    /**
+     * 远程查看（移动端/真机场景）：TraceBus → WS（devtoolsRelayPlugin 的 /proteus-source 端点）→
+     * 电脑浏览器 panel.html?ws= 下行查看。true = 同源自动（ws://location.host/proteus-source）；
+     * 对象形态可指定 path 与 appInfo（默认取 pages 数据）
+     */
+    remote?: boolean | {
+        path?: string;
+        appInfo?: () => unknown;
+    };
+    /**
+     * ★G-43 B4 所有权面板（缺省 true——挂全局默认图 getProteusOwnershipGraph + 内部 history）：
+     * 业务/容器已显式建图时可传 { graph }（或同时传 history 复用既有历史）；false 关闭。
+     * 数据进面板第十视图（本地面板）+ Proteus.ownership 远程命令（远程面板）。
+     */
+    ownership?: boolean | {
+        graph?: OwnershipGraph;
+        history?: OwnershipHistory;
+    };
+    /** 显式 traceBus（缺省 getProteusTraceBus 惰性单例） */
+    traceBus?: TraceBus;
+}
+export interface InstalledDevtools {
+    /** 业务侧发射端注入用（与 getProteusTraceBus 同实例） */
+    traceBus: TraceBus;
+    /** 卸载：store tracer dispose + 组件树订阅解绑 + 面板移除 */
+    destroy(): void;
+}
+/**
+ * 一键接入 Web 端 devtools（开发模式调用；生产 import.meta.env.DEV=false 且无 PROTEUS_DEBUG=1 时 bus 零开销 + 本地面板守卫挂载无事件）
+ * 用法（main.ts，interactive 阶段）：
+ *   const devtools = installProteusDevtools(app, { pinia, getConfig, setConfig, styleGuard, pages })
+ *   // 发射端同源：createRouter(routes, { traceBus: getProteusTraceBus() }) / createApi({ traceBus: getProteusTraceBus() })
+ */
+export declare function installProteusDevtools(app: App, options?: InstallDevtoolsOptions): InstalledDevtools;

package/dist/ownership-info.d.ts

@@ -0,0 +1,77 @@
+import type { OwnershipGraph, OwnershipHistory, OwnershipRecord, GraphNode } from '@proteus-vue/render-backend';
+export interface OwnershipResourceItem {
+    readonly id: string;
+    readonly type: string;
+    readonly byteSize: number;
+    readonly owner: string | null;
+    readonly state: GraphNode['state'];
+    readonly sourceLocation: string | null;
+    /** 活跃借用方（borrows edges from） */
+    readonly borrowedBy: string[];
+}
+export interface OwnershipViewData {
+    readonly summary: {
+        alive: number;
+        total: number;
+        bytesAlive: number;
+        byType: Record<string, {
+            allocated: number;
+            alive: number;
+        }>;
+    };
+    readonly diagnosis: {
+        orphans: Array<{
+            id: string;
+            type: string;
+            byteSize: number;
+            sourceLocation: string | null;
+        }>;
+        leaks: Array<{
+            resourceId: string;
+            type: string;
+            byteSize: number;
+            sourceLocation: string | null;
+            referenceChain: string[];
+        }>;
+        longBorrows: Array<{
+            resourceId: string;
+            borrowedBy: string;
+            owner: string | null;
+        }>;
+        crossPageRefs: Array<{
+            resourceId: string;
+            owner: string | null;
+            heldBy: string;
+        }>;
+    };
+    /** 按 owner 分组的存活资源（Graph 主视图——🟢 Owner + 📍 源码位置） */
+    readonly resources: Array<{
+        owner: string;
+        items: OwnershipResourceItem[];
+    }>;
+    /** alloc/drop 时间线（V-06 配对 + 未配对高亮；截断 tail 保留最新） */
+    readonly timeline: {
+        events: Array<OwnershipRecord & {
+            matchedAllocId?: string;
+        }>;
+        unpairedIds: string[];
+        truncated: boolean;
+    };
+}
+export interface OwnershipTracer {
+    /** 采集视图数据（面板 rerender / WS 响应共用；幂等纯读） */
+    collect(): OwnershipViewData;
+    dispose(): void;
+}
+export interface OwnershipTracerOptions {
+    /** 所有权图（缺省 getProteusOwnershipGraph 全局单例） */
+    graph?: OwnershipGraph;
+    /** 已有历史（业务在 graph 创建时挂的 createOwnershipHistory——缺省内部自建，从挂载时刻起记录） */
+    history?: OwnershipHistory;
+}
+/**
+ * ★G-43 B4：所有权 tracer——history + counters 常驻挂接，collect 一次跑齐视图数据。
+ * ★存量快照：history 只记录订阅后事件（面板后开场景）——collect 时对图内未出现过的节点补
+ *   'alloc' 快照记录（视为面板接入前已分配），时间线/未配对判定不丢存量。
+ */
+export declare function createOwnershipTracer(options?: OwnershipTracerOptions): OwnershipTracer;

package/dist/panel.d.ts

@@ -0,0 +1,39 @@
+import type { DevtoolsSource } from './source';
+import type { PagesViewData } from './views/pages';
+import type { DeviceInfo } from './views/device';
+import type { OwnershipViewData } from './views/ownership';
+import type { StoreRestoreEntry } from './snapshot-io';
+import type { DevToolsPlugin, KVStorage } from './plugins';
+export interface DevtoolsPanelOptions {
+    source: DevtoolsSource;
+    /** 时间旅行命令下发（缺省 no-op——业务侧适配器接入后生效） */
+    onTimeTravel?: (index: number) => void;
+    /** ★P1：状态应用（时间旅行回放 / 导入快照恢复共用）——panel 把 restore 快照交给 caller（install → pinia.$patch）；缺省仅面板内回放 */
+    onApplyState?: (stores: StoreRestoreEntry[]) => void;
+    /** ★P1：组件视图选中 → 页面元素高亮（install 侧 scrollIntoView + 描边闪烁） */
+    onSelectComponent?: (id: number) => void;
+    /** M9 插件：第三方自定义视图/事件订阅/命令（激活拓扑序，循环依赖报错，崩溃隔离） */
+    plugins?: DevToolsPlugin[];
+    /** 插件持久化存储（缺省内存 KV） */
+    storage?: KVStorage;
+    /** ★pages/依赖图面板：应用路由表 + 页面栈（缺省取 source.appInfo() 路由表；均无 → 空态） */
+    pages?: PagesViewData;
+    /** ★M8 设备面板：环境/能力信息钩子（本地面板 install 侧采集；缺省取 source.deviceInfo() 远程命令缓存；均无 → 空态） */
+    deviceInfo?: () => DeviceInfo;
+    /** ★G-43 B4 所有权面板：视图数据钩子（本地面板 install 侧 tracer 采集；缺省取 source.ownership() 远程命令缓存；均无 → 空态） */
+    ownershipData?: () => OwnershipViewData | undefined;
+}
+export interface DevtoolsPanel {
+    destroy(): void;
+    /** 切换视图（'timeline' | 'flamegraph' | 'state' | 'route' | 'errors' | 'components' | 'pages' | 'graph' | 'device' | 'ownership'） */
+    show(view: string): void;
+    /** ★P0：导出 store 快照 JSON（序列化 + Blob 下载，文件名 proteus-store-snapshot.json；返回序列化文本供程序化消费） */
+    exportSnapshot(): string;
+    /** ★P0：导入 store 快照 JSON（解析校验 → 数据重建 → 视图刷新 → onApplyState 应用回应用） */
+    importSnapshot(json: string): void;
+    /** ★M11 可观测性（M8.2）：导出 SessionBundle（可重放事件日志 + 设备 + store 快照；Blob 下载 proteus-session.json；返回序列化文本） */
+    exportSession(): string;
+    /** ★M11 可观测性（M8.2）：导入 SessionBundle（清空聚合 → 重放事件全视图重建 → onApplyState 应用最新状态） */
+    importSession(json: string): void;
+}
+export declare function createDevtoolsPanel(root: HTMLElement, options: DevtoolsPanelOptions): DevtoolsPanel;