@dimina-kit/devtools 0.3.2-dev.20260601115343 → 0.3.2-dev.20260610114009

package/README.md

@@ -2,16 +2,18 @@
 
 基于 Electron 的小程序开发者工具。提供模拟器、Chrome DevTools 面板、WXML/AppData/Storage 面板、编译配置等功能。
 
-下游 host 通过 [`@dimina-kit/workbench`](../workbench) 的 `workbench(config)` fluent API 集成并定制 devtools。扩展模型设计见 [`docs/workbench-model.md`](docs/workbench-model.md)。
+下游 host 通过 `launch(config)` 集成并定制 devtools（零配置直接 `launch()`，配置驱动 `launch({...})`；见下方「两种用法」）。两种用法都经领域中立的 [`@dimina-kit/electron-deck`](../electron-deck) 框架编排——框架接管 Electron 进程生命周期（whenReady / will-quit）、wire/trust 原语，devtools 作为 `RuntimeBackend` 注入完整运行时（见 [`framework-extraction-v2.md`](../electron-deck/docs/framework-extraction-v2.md)）。
 
 ---
 
-## 两种接入方式
+## 两种用法
 
-| 级别         | 入口                   | 控制力                | 适合场景       |
+单一入口 `launch(config?)`——不传配置即零配置直接运行，传 `WorkbenchAppConfig` 即配置驱动定制。
+
+| 用法         | 调用                   | 控制力                | 适合场景       |
 | ------------ | ---------------------- | --------------------- | -------------- |
 | **零配置**   | `launch()`             | 无                    | 直接运行       |
-| **配置驱动** | `createWorkbenchApp()` | 配置 Provider + 扩展点 | 品牌化、深度定制 |
+| **配置驱动** | `launch({...})`        | 配置 Provider + 扩展点 | 品牌化、深度定制 |
 
 ### 零配置
 
@@ -22,17 +24,17 @@ launch()
 
 ### 配置驱动
 
-扩展点分两类：**配置 Provider**（构造期、一对一，替换某个内置能力）走 `createWorkbenchApp` 配置字段；**Contribution**（`onSetup` 期、一对多，添加多个同类条目）走 `onSetup(instance)` 上的 typed 方法。所有 Contribution 都 per-context，随 context 自动销毁。
+扩展点分两类：**配置 Provider**（构造期、一对一，替换某个内置能力）走 `launch` 配置字段；**Contribution**（`onSetup` 期、一对多，添加多个同类条目）走 `onSetup(instance)` 上的 typed 方法。所有 Contribution 都 per-context，随 context 自动销毁。
 
 ```typescript
 import { suppressEpipe } from '@dimina-kit/devtools/bootstrap'
-import { createWorkbenchApp } from '@dimina-kit/devtools/app'
+import { launch } from '@dimina-kit/devtools'
 import { rendererDir } from '@dimina-kit/devtools/paths'
 import { Menu } from 'electron'
 
 suppressEpipe()
 
-createWorkbenchApp({
+launch({
   // ── 配置 Provider（构造期，一对一）──
   appName: '我的开发工具',
   adapter: myAdapter,
@@ -53,14 +55,10 @@ createWorkbenchApp({
     instance.registerSimulatorApi('login', (params) => myLogin(params))
 
     // 工具栏：整表替换，随 host 状态（如登录态）重算时再 set 一次
-    const refreshToolbar = () => {
-      const currentUser = getCurrentUser()
-      instance.toolbar.set([
-        { id: 'account', label: '当前用户', kind: 'avatar', placement: 'leading', displayInitial: currentUser?.name, avatarUrl: currentUser?.avatar, handler: () => showAccount() },
-        { id: 'preview', label: '预览', placement: 'primary', handler: () => preview() },
-        { id: 'deploy', label: '发布', placement: 'trailing', handler: () => deploy() },
-      ])
-    }
+    const refreshToolbar = () => instance.toolbar.set([
+      { id: 'deploy', label: '发布', handler: () => deploy() },
+      { id: 'preview', label: '预览', handler: () => preview() },
+    ])
     refreshToolbar()
 
     // 自定义 IPC：经 gated 的 IpcRegistry，不再裸 ipcMain.handle
@@ -70,16 +68,10 @@ createWorkbenchApp({
     // const win = createDialogWindow(/* ... */)
     // instance.registerTrustedWindow(win)
   },
-  onBeforeOpenProject: async ({ projectPath, instance }) => {
-    const ok = await canOpenProject(projectPath)
-    return ok
-      ? { allow: true }
-      : { allow: false, reason: '当前账号没有项目权限' }
-  },
   onBeforeClose: ({ context }) => {
     // 窗口关闭前的自定义清理；session 关闭和 view 销毁由框架自动处理
   },
-}).start()
+})
 ```
 
 > Contribution 注册物全部自动进 `context.registry`，host 无需手写 cleanup。devtools 内部仍用 `WorkbenchModule` 组织内置 IPC 模块，但这是实现细节，不再作为对外接入方式导出。
@@ -98,7 +90,7 @@ src/
     api.ts                               # 公共 API 聚合入口（package main）
     app/
       launch.ts                          # 零配置入口
-      app.ts                             # createWorkbenchApp 工厂
+      app.ts                             # createDevtoolsRuntime 装配体 + runDevtoolsBootstrap
       bootstrap.ts                       # suppressEpipe / setupCdpPort
       lifecycle.ts                       # Electron app 生命周期注册
     ipc/                                 # 只做 handler 注册，不写业务
@@ -128,8 +120,7 @@ src/
       default-adapter.ts                 # 默认 CompilationAdapter
     menu/                                # 应用菜单
     utils/
-      paths.ts                           # rendererDir / defaultPreloadPath / simulatorDir
-      disposable.ts                      # DisposableRegistry + AggregateError 聚合
+      paths.ts                           # rendererDir / defaultPreloadPath / simulatorDir / cjsSiblingPreloadPath
       ipc-registry.ts                    # ipcMain.handle 包装 + SenderPolicy 闸门
       sender-policy.ts                   # sender webContents id 白名单
       ipc-schema.ts                      # zod schema 校验工具
@@ -141,7 +132,7 @@ src/
   preload/                               # 按注入目标分
     windows/                             # contextBridge 类型 preload
       main.ts                            # workbench 三窗口 preload，仅暴露 window.devtools.ipc
-      simulator.ts                       # simulator webview 的默认 preload
+      simulator.ts                       # simulator（WCV）frame preload（native-host 跑其 .cjs sibling）
     shared/                              # preload 之间共享
       api-compat.ts                      # setupApiCompatHook
       constants.ts
@@ -150,7 +141,6 @@ src/
       console.ts                         # 控制台拦截
       app-data.ts                        # Worker setData 拦截 → createAppDataSource
       wxml.ts                            # Vue 组件树提取 → createWxmlSource
-      disposable.ts                      # instrumentation 共用的清理工具
     miniapp-snapshot/                    # 面板数据统一快照框架（docs/miniapp-snapshot.md）
       types.ts                           # MiniappSnapshotSource / SnapshotEnvelope
       host.ts                            # createMiniappSnapshotHost → push/pull/__miniappSnapshot
@@ -191,21 +181,21 @@ src/
 
 ### WorkbenchConfig
 
-`launch()` 和 `createWorkbenchApp()` 共用：
+`launch()` 接受的基础字段（`WorkbenchConfig`）：
 
 | 字段               | 类型                 | 默认值              | 说明                               |
 | ------------------ | -------------------- | ------------------- | ---------------------------------- |
 | `appName`          | `string`             | `'Dimina DevTools'` | 窗口标题                           |
 | `adapter`          | `CompilationAdapter` | 内置                | 项目编译适配器                     |
 | `panels`           | `BuiltinPanelId[]`   | 全部四个            | 显示哪些内置面板                   |
-| `preloadPath`      | `string`             | 内置                | 自定义 preload 脚本路径            |
+| `preloadPath`      | `string`             | 内置                | 统一的 host 级 preload 入口；native-host simulator（WCV）自动跑其 `.cjs` sibling（`cjsSiblingPreloadPath`） |
 | `apiNamespaces`    | `string[]`           | `[]`                | 自定义 API 命名空间（如 `['qd']`） |
 | `brandingProvider` | `() => { appName }`  | —                   | 品牌信息 provider                  |
 | `headerHeight`     | `number`             | `40`                | 头部栏高度（px），同步下发 main + renderer |
 
 ### WorkbenchAppConfig（扩展 WorkbenchConfig）
 
-`createWorkbenchApp()` 额外支持：
+`launch()` 完整接受的 `WorkbenchAppConfig` 额外支持：
 
 | 字段            | 类型                                        | 默认值      | 说明                                              |
 | --------------- | ------------------------------------------- | ----------- | ------------------------------------------------- |
@@ -213,9 +203,8 @@ src/
 | `rendererDir`   | `string`                                    | 内置        | 自定义 renderer HTML 目录                         |
 | `icon`          | `string`                                    | —           | 窗口/任务栏图标路径（macOS 使用 app bundle 图标） |
 | `menuBuilder`   | `(mainWindow, menuContext: MenuContext) => void` | 内置菜单 | 自定义菜单构建器；`menuContext` 为收窄后的 `MenuContext`，不含 `registry`/`senderPolicy` 等内部管线 |
-| `onSetup`       | `(instance) => void \| Promise<void>`       | —           | 窗口和 context 创建后的回调，用于注册 Contribution（见下文）|
-| `onBeforeOpenProject` | `({ projectPath, instance }) => BeforeOpenProjectResult \| Promise<BeforeOpenProjectResult>` | — | 项目目录校验通过后、关闭当前 session 和编译新项目之前的宿主准入钩子 |
-| `onBeforeClose` | `(instance) => void \| Promise<void>`       | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
+| `onSetup`       | `(instance) => void`                        | —           | 窗口和 context 创建后的回调，用于注册 Contribution（见下文）|
+| `onBeforeClose` | `(instance) => void`                        | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
 | `window`        | `WorkbenchWindowConfig`                     | —           | 窗口尺寸覆盖                                      |
 | `updateChecker` | `UpdateChecker`                             | —           | 自定义更新检查器；提供后启用"检查更新"功能        |
 | `updateOptions` | `{ checkInterval?, initialDelay?, getCurrentVersion? }` | —  | 仅当 `updateChecker` 提供时生效，默认 1h / 5s     |
@@ -231,8 +220,6 @@ src/
 | `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
 | `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
 
-`onSetup` 可以返回 Promise；`createWorkbenchApp().start()` 会等待 `onSetup` 解析完成后才继续后续启动流程，因此宿主在 `onSetup` 内注册的 simulator API 会早于 simulator `<webview>` 首次枚举自定义 API。
-
 ### 内置面板 ID
 
 `'wxml'` \| `'console'` \| `'appdata'` \| `'storage'`
@@ -245,7 +232,7 @@ src/
 
 ## Embedding & Extending the Project Panel
 
-宿主（如 qdmp）通过 `createWorkbenchApp({...})` 嵌入 devtools 时，可对项目面板做三个正交扩展：
+宿主（如 qdmp）通过 `launch({...})` 嵌入 devtools 时，可对项目面板做三个正交扩展：
 
 | 扩展点 | 用途 |
 | --- | --- |
@@ -264,7 +251,7 @@ src/
 ### 最小示例
 
 ```typescript
-import { createWorkbenchApp } from '@dimina-kit/devtools/app'
+import { launch } from '@dimina-kit/devtools'
 import type { ProjectsProvider, ProjectTemplate } from '@dimina-kit/devtools/projects-provider'
 import { BrowserWindow } from 'electron'
 
@@ -306,7 +293,7 @@ const qdmpBlank: ProjectTemplate = {
   source: { type: 'directory', path: '/abs/path/to/template' },
 }
 
-createWorkbenchApp({
+launch({
   projectsProvider: provider,
   projectTemplates: [qdmpBlank],
   builtinTemplates: ['taro-todo'], // 只保留 taro-todo，干掉默认 blank
@@ -325,7 +312,7 @@ createWorkbenchApp({
       win.on('closed', () => resolve(null))
     })
   },
-}).start()
+})
 ```
 
 ### `customCreateProjectDialog` 返回值
@@ -389,13 +376,13 @@ const myAdapter: CompilationAdapter = {
 
 ## Preload Instrumentation
 
-模拟器 webview 注入 preload 脚本，在 webview 全局上安装两类东西：**桥接**（把数据通道暴露到 webview）+ **instrumentation**（监听运行时事件并写入桥接）。内置 preload 见 `src/preload/windows/simulator.ts`。
+模拟器 frame 注入 preload 脚本，在其全局上安装两类东西：**桥接**（把数据通道暴露到运行时全局）+ **instrumentation**（监听运行时事件并写入桥接）。内置 preload 见 `src/preload/windows/simulator.ts`（native-host simulator 跑其 `.cjs` sibling）。
 
 ### 必装：桥接
 
 | 函数 | 作用 | 不装会怎样 |
 | --- | --- | --- |
-| `installSimulatorBridge()` | 暴露 `window.__simulatorData`，承载 `highlightElement` / `unhighlightElement` / `getAppdata` / `getWxml` / `getStorageSnapshot` 等只读 API（供主进程 `executeJavaScript` 拉取） | 元素选区 overlay 不显示；automation `Page.getData` 返回空对象；MCP `simulator_get_overview` 在 hints 中追加 `simulator bridge not ready (window.__simulatorData missing)`。注：Storage 面板走主进程 CDP，不受影响；Console/AppData/WXML 推送走 `sendToHost`，也不受影响 |
+| `installSimulatorBridge()` | 暴露 `window.__simulatorData`，承载 `highlightElement` / `unhighlightElement` / `getAppdata` / `getWxml` / `getStorageSnapshot` 等只读 API（供主进程 `executeJavaScript` 拉取） | 元素选区 overlay 不显示；automation `Page.getData` 返回空对象；MCP `simulator_get_overview` 在 hints 中追加 `simulator bridge not ready (window.__simulatorData missing)`。注：三个右侧面板的数据都另有来源（Storage 走主进程 CDP；AppData/WXML 走主进程 `SimulatorAppDataChannel` / `SimulatorWxmlChannel`；Console 走 render-host/service-host guest preload → 主进程 `consoleLog`），均不依赖 `window.__simulatorData`，不受影响 |
 | `installCustomApisBridge()` | 暴露 `window.__diminaCustomApis`，承载 `list` / `invoke`，让模拟器侧把主进程注册的 API 代理回小程序 runtime | `registerSimulatorApi` 注册的业务 API 在小程序里调用全部 no-op（参见下方 "Simulator 自定义 API"） |
 | `setupApiCompatHook()` | 兼容上游 API 名称变更 | 部分 API 调用兼容性问题 |
 
@@ -403,14 +390,16 @@ const myAdapter: CompilationAdapter = {
 
 ### 按需：instrumentation
 
-Console 是独立 instrumentation；AppData 与 WXML 已迁移到 **miniappSnapshot** 框架——各自实现一个 `MiniappSnapshotSource`，由 `MiniappSnapshotHost` 统一负责推送 / 拉取 / reload 重同步（详见 `docs/miniapp-snapshot.md`）。
+这些探针是**可组合的 preload API**：`@dimina-kit/devtools/preload` 把它们导出，供下游自己拼装自定义 preload。下表是各探针自身的契约（捕获什么 + 推到哪个通道）。
 
 | 探针 | 捕获内容 | 数据通道 |
 | --- | --- | --- |
-| `installConsoleInstrumentation()` | `console.*`、`window.onerror`、未捕获 rejection | `sendToHost` |
+| `installConsoleInstrumentation()` | `console.*`、`window.onerror`、未捕获 rejection | `sendToHost`（guest → embedder） |
 | `createAppDataSource()` | Worker `ub` 消息、setData / page init | miniappSnapshot 框架（`miniapp-snapshot:push`） |
 | `createWxmlSource()` | Vue 组件树提取、MutationObserver 自动更新 | miniappSnapshot 框架（`miniapp-snapshot:push`） |
 
+> ⚠️ **内置 native-host 运行时并不靠这条 `miniapp-snapshot:push` 通道喂面板**：右侧 WXML / AppData 面板的数据由主进程服务（`SimulatorWxmlChannel` / `SimulatorAppDataChannel`）直接供给（见下方「数据流」）。内置 simulator preload 仍调用 `createAppDataSource().start()`，但只为副作用（填 `window.__simulatorData.getAppdata()` 供 automation / MCP 读取），并**不**把它 wrap 进 `MiniappSnapshotHost`——所以 `miniapp-snapshot:push` 在内置路径下无消费者。该框架契约（含 `createWxmlSource`）仍为外部/组合式 preload 保留导出（详见 `docs/miniapp-snapshot.md`）。
+
 > Storage 面板的数据由主进程通过 CDP `DOMStorage` 域抓取（`src/main/services/simulator-storage`），**不需要 preload 侧 instrumentation**。
 
 各面板的数据流详见下方 "数据流" 章节。
@@ -476,7 +465,7 @@ launch({ preloadPath: '/absolute/path/to/my-preload.js' })
 | `wx.getStorage(...)` 覆盖内置 | `'getStorage'`（小心：这会**屏蔽** dimina 容器的实现） |
 
 ```typescript
-createWorkbenchApp({
+launch({
   onSetup: (instance) => {
     // 提供 wx.login 的实现（dimina 容器默认未实现，注册后才能用）
     const dispose = instance.registerSimulatorApi('login', async ({ success }) => {
@@ -508,13 +497,12 @@ createWorkbenchApp({
 `@dimina-kit/devtools` 的公共入口。`api.ts`（根入口）聚合了所有公共 API，优先从根入口导入。
 
 ```
-@dimina-kit/devtools                        launch, createWorkbenchApp, buildDefaultMenu,
+@dimina-kit/devtools                        launch, buildDefaultMenu,
                                        openSettingsWindow, suppressEpipe, setupCdpPort,
                                        createWorkbenchContext, createMainWindow,
                                        createViewManager, IpcRegistry,
                                        UpdateManager, createGitHubReleaseChecker, ...
 @dimina-kit/devtools/launch                 launch(config?), buildDefaultMenu, openSettingsWindow
-@dimina-kit/devtools/app                    createWorkbenchApp(config?)
 @dimina-kit/devtools/types                  TypeScript 类型定义
 @dimina-kit/devtools/bootstrap              suppressEpipe(), setupCdpPort()
 @dimina-kit/devtools/context                createWorkbenchContext(opts),
@@ -587,21 +575,23 @@ interface WorkbenchContext {
 flowchart TB
     subgraph BW["BrowserWindow"]
         direction TB
-        Z3["⑤ popoverView &nbsp;[z=3，顶层]<br/>entries/popover/index.html<br/>全屏透明遮罩 + 编译配置表单"]
-        Z2["④ settingsView &nbsp;[z=2]<br/>entries/settings/index.html<br/>固定宽度 320px，右侧对齐"]
-        Z1["② simulatorView &nbsp;[z=1]<br/>Chrome DevTools 面板"]
-        subgraph Z0["① mainWindow &nbsp;[z=0，底层]&nbsp;entries/main/index.html"]
+        Z4["⑤ popoverView &nbsp;[顶层]<br/>entries/popover/index.html<br/>全屏透明遮罩 + 编译配置表单"]
+        Z3["④ settingsView<br/>entries/settings/index.html<br/>固定宽度 320px，右侧对齐"]
+        Z2["② simulatorView<br/>Chrome DevTools 面板（绑到活跃 render-host guest / service host）"]
+        Z1["① nativeSimulatorView : WebContentsView<br/>模拟器主进程顶层 WCV（跑 simulator/main.tsx 的 DeviceShell）<br/>partition=persist:simulator，托管每页 render-host &lt;webview&gt; guest"]
+        subgraph Z0["⓪ mainWindow &nbsp;[底层]&nbsp;entries/main/index.html"]
             direction LR
-            SIM["模拟器 &lt;webview&gt;<br/>拖拽分割线"]
+            SIM["&lt;SimulatorPanel&gt; 占位 / 锚点<br/>（仅 nativeSimulatorView 的 bounds target，无 webview）"]
             PNL["WXML / AppData / Storage<br/>React 中直接渲染"]
         end
+        Z4 -. 覆盖 .-> Z3
         Z3 -. 覆盖 .-> Z2
         Z2 -. 覆盖 .-> Z1
         Z1 -. 覆盖 .-> Z0
     end
 ```
 
-层级由 `addChildView()` 调用顺序决定，后添加的 View 在上层。内置面板（WXML / AppData / Storage）不使用独立 WebContentsView，直接在主窗口 React 中渲染；只有 Chrome DevTools / settings / popover 需要 View 覆盖。
+层级由 `addChildView()` 调用顺序决定，后添加的 View 在上层。overlay 栈里有**两个不同的** simulator 相关 view：`nativeSimulatorView`（模拟器本体，主进程顶层 `WebContentsView`，跑 `simulator/main.tsx` 的 DeviceShell，内部托管每页 render-host `<webview>` guest）和 `simulatorView`（Chrome DevTools 面板本身，绑到活跃 render-host guest / service host）。模拟器**不是** mainWindow renderer 里的 `<webview>`——主 renderer 的 `<SimulatorPanel>` 只画一个空占位 div 当 `nativeSimulatorView` 的 bounds 锚点（手机框 / 圆角 / 刘海 / 页面 `<webview>` 都在那个 WCV 内部的 DeviceShell 里）。内置面板（WXML / AppData / Storage）不使用独立 WebContentsView，直接在主窗口 React 中渲染；只有 nativeSimulator / Chrome DevTools / settings / popover 需要 View 覆盖。
 
 ### 数据流
 
@@ -609,10 +599,10 @@ flowchart TB
 
 | 面板 / 场景 | 模式 | 路径 |
 | --- | --- | --- |
-| Console | 推送 | `installConsoleInstrumentation` 经 `runtime/host.ts:sendToHost` → webview `ipcRenderer.sendToHost` 推到宿主 → renderer 监听 `ipc-message` |
-| AppData / WXML 树 | 推送 + 拉取 | **miniappSnapshot 框架**：preload `MiniappSnapshotHost` 经 `miniapp-snapshot:push` 推全量快照，renderer `useMiniappSnapshot` 整份投影；面板「刷新」走 `miniapp-snapshot:pull`（详见 `docs/miniapp-snapshot.md`） |
+| Console | 推送 | render-host / service-host preload monkeypatch `console.*` → 主进程 `consoleLog` 容器消息 → bridge-router → `ctx.guestConsole.emit` → `services/console-forward`。render（视图）层条目以 `[视图]` 前缀注入挂在 service host 上的 Chrome DevTools，service 层本就原生显示在同一面板；automation WS 等外部订阅者也从这里 fan-out |
+| AppData / WXML 树 | 推送 + 拉取 | 主进程服务，镜像 Storage 的 main→renderer 契约：WXML 由 `services/simulator-wxml` 经 render-inspect 从活跃 render-host `<webview>` guest 拉树（`SimulatorWxmlChannel.GetSnapshot`），render 活动时推 `SimulatorWxmlChannel.Event`；AppData 由 `services/simulator-appdata` 在 bridge-router 里 tap service→render 的 setData 流，推 `SimulatorAppDataChannel.Event` |
 | Storage | 拉取 + 推送 | renderer `ipcInvoke(SimulatorStorageChannel.GetSnapshot)` → 主进程 CDP `DOMStorage` 域；变更事件由主进程通过 `SimulatorStorageChannel.Event` 推回 renderer |
-| 元素选区 / `Page.getData` / MCP overview | 拉取 | 主进程 `webContents.executeJavaScript(...)` 或 `Runtime.evaluate(...)` 读 `window.__simulatorData.*`（由 `installSimulatorBridge` 暴露）；面板快照亦可经 `window.__miniappSnapshot.get(id)` 同步读取（由 `MiniappSnapshotHost` 暴露） |
+| 元素选区 / `Page.getData` / MCP overview | 拉取 | 主进程 `webContents.executeJavaScript(...)` 或 `Runtime.evaluate(...)` 读 `window.__simulatorData.*`（由 `installSimulatorBridge` 暴露） |
 
 > `src/main/ipc/panels.ts` 暴露 `panel:eval` handler 供外部 host 自定义面板复用，内置 renderer 不消费它。
 
@@ -630,14 +620,14 @@ Electron 对 `chrome.devtools.panels.create()` 的支持**长期不稳定**。
 
 **影响范围**：从 Electron 7 到 39 均有报告（[#23662](https://github.com/electron/electron/issues/23662)、[#41613](https://github.com/electron/electron/issues/41613)、[#48705](https://github.com/electron/electron/issues/48705)），非特定版本 bug，而是系统性实现缺陷。官方文档声称完全支持，但实际因竞态条件和实现不完整导致面板无法可靠渲染。Electron 团队无修复计划。
 
-**当前方案**：内置面板（WXML / AppData / Storage）直接在主窗口 React 中渲染，通过 `panel:eval` IPC 调用 `webContents.executeJavaScript()` 从 simulator 拉取数据；Chrome DevTools 仍作为独立 `WebContentsView` 通过 `setDevToolsWebContents()` 挂载。面板切换由 renderer toolbar 的 tab 栏控制，主进程负责 simulator/settings/popover View 的创建、定位和显隐。详见 `src/main/ipc/panels.ts` 和 `src/main/ipc/simulator.ts`。
+**当前方案**：内置面板（WXML / AppData / Storage）直接在主窗口 React 中渲染，数据由主进程服务直接供给——WXML / AppData 走 `SimulatorWxmlChannel` / `SimulatorAppDataChannel`（main → renderer 的 seed `GetSnapshot` + push `Event`），Storage 走 CDP `DOMStorage` 域（详见上方「数据流」）；Chrome DevTools 仍作为独立 `WebContentsView` 通过 `setDevToolsWebContents()` 挂载。面板切换由 renderer toolbar 的 tab 栏控制，主进程负责 nativeSimulator/settings/popover View 的创建、定位和显隐。详见 `src/main/ipc/panels.ts` 和 `src/main/ipc/simulator.ts`。
 
 ---
 
 ## 调试
 
 - **Cmd+Shift+I** / **Ctrl+Shift+I** — 打开 mainWindow 的 Electron DevTools（调试 React 渲染层）
-- 模拟器 webview 的 Chrome DevTools 在编译完成、`dom-ready` 后自动打开
+- 模拟器活跃 render-host `<webview>` guest 的 Chrome DevTools 在编译完成、`dom-ready` 后自动打开
 - 开发模式（`!app.isPackaged`）下 mainWindow DevTools 自动以 detach 模式打开
 
 ---
@@ -661,7 +651,7 @@ pnpm test               # 运行测试
 本工具仅用于本地开发调试。当前的安全配置：
 
 - **Workbench 窗口**（main / settings / popover overlay）均启用 `contextIsolation` 并禁用 `nodeIntegration`；renderer 通过 main preload 经 `contextBridge` 拿到 `window.devtools.ipc`，每个 IPC handler 经 sender whitelist 校验调用方
-- **Simulator 加载的小程序代码** 运行在独立 `<webview>` 中（`partition='persist:simulator'`、`nodeIntegration=false`），preload 由 `session.registerPreloadScript` 在 session 层固定，渲染进程无法替换
+- **Simulator 本体** 是主进程顶层 `WebContentsView`（`nativeSimulatorView`，`partition='persist:simulator'`、`nodeIntegration=false`），其 preload 由 `webPreferences.preload = cjsSiblingPreloadPath(ctx.preloadPath)` 在创建时（`attachNativeSimulator`）固定；session 层的 `configureSimulatorSession()` 只设 Referer/CORS 头，不注册 frame preload。**小程序的每页代码** 运行在该 WCV 内部 DeviceShell 托管的 render-host `<webview>` guest 里（同 `persist:simulator` partition、`nodeIntegration=false`），承载逐页沙箱；guest 的 contextIsolation/sandbox 由主进程 `will-attach-webview` 钉死，渲染进程无法替换
 - **renderer 入口** 启用了保守 CSP；`will-navigate` / `setWindowOpenHandler` 屏蔽外部跳转
 
 仍然不要在 devtools 窗口中加载不受信任的远程内容；本工具不打算在非本地环境部署。
@@ -670,6 +660,6 @@ pnpm test               # 运行测试
 
 内置的 MCP server 默认关闭，由 `startMcpServer` 入口显式启动，或通过 workbench 设置中的 `mcp.enabled` 开启。开启后会在本机监听 SSE 端点，向任何可以连接到该端点的 MCP 客户端暴露一组工具，能力包括：读取 DOM 结构、截屏、拉取网络日志、触发导航等。
 
-`workbench_evaluate` 已从 MCP 工具集中移除，workbench 只暴露只读诊断工具（截屏、console 日志、DOM、网络日志等）。`simulator_evaluate` 仍然保留，但 simulator 使用 `<webview>`、`nodeIntegration=false`，其 `evaluate` 仅在页面 JS 上下文执行，不具备 Node API 访问能力。
+`workbench_evaluate` 已从 MCP 工具集中移除，workbench 只暴露只读诊断工具（截屏、console 日志、DOM、网络日志等）。`simulator_evaluate` 仍然保留，但小程序页面跑在 render-host `<webview>` guest 里（`nodeIntegration=false`），其 `evaluate` 仅在页面 JS 上下文执行，不具备 Node API 访问能力。
 
 仅在连接到可信的本机 MCP 客户端或被信任的 AI 工具时启用该功能；不要在公共 WiFi、共享机器或存在远程 SSH 端口转发的场景下开启，以免监听端口被非预期的客户端访问。

package/dist/main/api.d.ts

@@ -1,5 +1,4 @@
 export { launch, buildDefaultMenu, openSettingsWindow } from './app/launch.js';
-export { createWorkbenchApp } from './app/app.js';
 export type { WorkbenchAppInstance } from './app/app.js';
 export { suppressEpipe, setupCdpPort } from './app/bootstrap.js';
 export { createWorkbenchContext, hasBuiltinPanel, getDefaultTab } from './services/workbench-context.js';
@@ -15,5 +14,5 @@ export { IpcRegistry } from './utils/ipc-registry.js';
 export type { SenderPolicy } from './utils/ipc-registry.js';
 export { UpdateManager, createGitHubReleaseChecker } from './services/update/index.js';
 export type { UpdateManagerOptions, GitHubReleaseCheckerOptions, PickAssetContext, VersionScheme, } from './services/update/index.js';
-export type { BeforeOpenProjectHook, BeforeOpenProjectResult, WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, ToolbarAction, ToolbarActionInput, ToolbarActionKind, ToolbarActionPlacement, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
+export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, ToolbarAction, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
 //# sourceMappingURL=api.d.ts.map

package/dist/main/api.js

@@ -1,6 +1,10 @@
 // ── Primary API ──────────────────────────────────────────────────────────
+// `launch` boots through the @dimina-kit/electron-deck framework
+// (process-lifecycle gate + wire/trust) with the devtools RuntimeBackend
+// supplying the full runtime. The instance builder (`createDevtoolsRuntime`) is
+// internal — hosts integrate via `launch(config)`; the `WorkbenchAppInstance`
+// type (what `onSetup(instance)` receives) is re-exported for typing host callbacks.
 export { launch, buildDefaultMenu, openSettingsWindow } from './app/launch.js';
-export { createWorkbenchApp } from './app/app.js';
 // ── Bootstrap utilities ──────────────────────────────────────────────────
 export { suppressEpipe, setupCdpPort } from './app/bootstrap.js';
 // ── Context & views (for module-assembly consumers) ──────────────────────

package/dist/main/app/app.d.ts

@@ -4,7 +4,7 @@ import type { SimulatorApiHandler } from '../services/simulator/custom-apis.js';
 import { type WorkbenchContext } from '../services/workbench-context.js';
 import { type AutomationServer } from '../services/automation/index.js';
 import { UpdateManager } from '../services/update/index.js';
-import { type Disposable } from '../utils/disposable.js';
+import { type Disposable } from '@dimina-kit/electron-deck/main';
 import { IpcRegistry } from '../utils/ipc-registry.js';
 export interface WorkbenchAppInstance {
     mainWindow: BrowserWindow;
@@ -23,8 +23,18 @@ export interface WorkbenchAppInstance {
     updateManager?: UpdateManager;
     dispose: () => Promise<void>;
 }
-export declare function createWorkbenchApp(config?: WorkbenchAppConfig): {
-    setup: () => Promise<WorkbenchAppInstance>;
-    start: () => Promise<void>;
-};
+/**
+ * Pre-ready bootstrap side effects (app name, CDP port, CSP suppression,
+ * privileged scheme). MUST run before `app.whenReady()`. Extracted so the `RuntimeBackend.beforeReady` hook (which launch()
+ * routes through) runs it before the framework awaits app.whenReady().
+ */
+export declare function runDevtoolsBootstrap(config?: WorkbenchAppConfig): void;
+/**
+ * Domain runtime assembly — the post-whenReady body. Builds the main window +
+ * context, registers IPC modules, stands up simulator/storage/CDP/native-host
+ * services, and returns the fat {@link WorkbenchAppInstance}. Extracted so the
+ * v2 `RuntimeBackend.assemble` reuses the exact same body (parity by shared
+ * implementation, not behavioural re-creation).
+ */
+export declare function createDevtoolsRuntime(config?: WorkbenchAppConfig): Promise<WorkbenchAppInstance>;
 //# sourceMappingURL=app.d.ts.map