@dimina-kit/devtools 0.3.2-dev.20260611060732 → 0.3.2-dev.20260611135124

package/README.md

@@ -41,7 +41,6 @@ launch({
   preloadPath: '/path/to/my-preload.js',
   rendererDir,
   apiNamespaces: ['my'],
-  headerHeight: 72,
   brandingProvider: () => ({ appName: '我的开发工具' }),
   icon: '/path/to/icon.png',
   menuBuilder: (mainWindow, menuCtx) => {
@@ -54,13 +53,6 @@ launch({
     // simulator 自定义 API：per-context
     instance.registerSimulatorApi('login', (params) => myLogin(params))
 
-    // 工具栏：整表替换，随 host 状态（如登录态）重算时再 set 一次
-    const refreshToolbar = () => instance.toolbar.set([
-      { id: 'deploy', label: '发布', handler: () => deploy() },
-      { id: 'preview', label: '预览', handler: () => preview() },
-    ])
-    refreshToolbar()
-
     // 自定义 IPC：经 gated 的 IpcRegistry，不再裸 ipcMain.handle
     instance.ipc.handle('my:action', () => collectStats())
 
@@ -95,9 +87,7 @@ src/
       lifecycle.ts                       # Electron app 生命周期注册
     ipc/                                 # 只做 handler 注册，不写业务
       index.ts                           # 聚合 register 函数导出
-      simulator.ts                       # simulator attach/detach/resize
-      panels.ts                          # panel:list / panel:eval / selectSimulator
-      toolbar.ts                         # 品牌 / 工具栏配置
+      simulator.ts                       # simulator attach/detach/设备信息/custom-api invoke
       popover.ts                         # 编译配置弹窗
       settings.ts                        # 项目设置 + workbench 设置
       projects.ts                        # 项目列表管理
@@ -187,11 +177,11 @@ src/
 | ------------------ | -------------------- | ------------------- | ---------------------------------- |
 | `appName`          | `string`             | `'Dimina DevTools'` | 窗口标题                           |
 | `adapter`          | `CompilationAdapter` | 内置                | 项目编译适配器                     |
-| `panels`           | `BuiltinPanelId[]`   | 全部四个            | 显示哪些内置面板                   |
+| `panels`           | `BuiltinPanelId[]`   | —                   | **已废弃，运行时忽略**：界面恒显示全部四个内置面板；保留字段仅为兼容仍传它的 host |
 | `preloadPath`      | `string`             | 内置                | 统一的 host 级 preload 入口；native-host simulator（WCV）自动跑其 `.cjs` sibling（`cjsSiblingPreloadPath`） |
 | `apiNamespaces`    | `string[]`           | `[]`                | 自定义 API 命名空间（如 `['qd']`） |
 | `brandingProvider` | `() => { appName }`  | —                   | 品牌信息 provider                  |
-| `headerHeight`     | `number`             | `40`                | 头部栏高度（px），同步下发 main + renderer |
+| `headerHeight`     | `number`             | —                   | **已废弃，运行时忽略**：头部栏恒为 40px（`HEADER_H`）；需要自定义工具栏请用 host toolbar WCV |
 
 ### WorkbenchAppConfig（扩展 WorkbenchConfig）
 
@@ -216,7 +206,6 @@ src/
 | 方法 | 说明 |
 | --- | --- |
 | `instance.registerSimulatorApi(name, handler)` | 注册 simulator 自定义 API，小程序里 `wx.<name>()` 调用（详见下方"Simulator 自定义 API"）。返回 `Disposable` |
-| `instance.toolbar.set(actions)` | 原子整表替换工具栏；`actions` 为 `ToolbarActionInput[]`（`{ id, label, handler }`），`id` 重复抛错。host 状态变化（如登录态）时构造新表再 `set` 一次 |
 | `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
 | `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
 
@@ -492,6 +481,33 @@ launch({
 
 ---
 
+## Host Toolbar（宿主自定义工具栏）
+
+下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素）。
+
+### 双向消息：onMessage / send
+
+主进程与工具栏页面之间有一条门控窄通道（按 load 握手的 MessagePort，信封 `{ channel, payload }`）：
+
+- `hostToolbar.onMessage(channel, handler): { dispose() }` — 接收页面消息。控制面级注册：可在 view 创建前调用，且跨页面 reload 自动续接，无需重新注册。空串/非 string channel 抛错。
+- `hostToolbar.send(channel, payload): boolean` — 发消息给页面。门控不排队：没有活的工具栏 webContents、本次 load 的握手未完成、或正处于换文档导航窗口期（`loadURL`/`loadFile` 发起后、以及页面自发的主框架跨文档导航开始后，直到新文档握手完成）时返回 `false`（不投递、不建 view）；返回 `true` 即已发出。返回值本身就是就绪信号，下游不再需要拿 `getHostToolbarWebContentsId()` 手工判断工具栏是否就绪（该 API 保留）。
+
+页面侧由框架自动注入 `window.diminaHostToolbar`（仅 `{ send, onMessage }` 两个函数；握手前的 `send` 进队列、握手后按序送达。队列上限 128 条：超限丢弃最新一条、首次超限 console.warn 一次，不抛错）：
+
+```js
+// 工具栏页面内
+window.diminaHostToolbar.onMessage('host:cmd', (payload) => { /* ... */ })
+window.diminaHostToolbar.send('page:event', { clicked: 'compile' })
+```
+
+```ts
+// 主进程（onSetup 内）
+const sub = instance.context.views.hostToolbar.onMessage('page:event', (payload) => { /* ... */ })
+instance.context.views.hostToolbar.send('host:cmd', { theme: 'dark' }) // false = 未送达
+```
+
+---
+
 ## 模块导出一览
 
 `@dimina-kit/devtools` 的公共入口。`api.ts`（根入口）聚合了所有公共 API，优先从根入口导入。
@@ -499,14 +515,14 @@ launch({
 ```
 @dimina-kit/devtools                        launch, buildDefaultMenu,
                                        openSettingsWindow, suppressEpipe, setupCdpPort,
+                                       asMiniappRuntime, MiniappRuntime（type）,
                                        createWorkbenchContext, createMainWindow,
                                        createViewManager, IpcRegistry,
                                        UpdateManager, createGitHubReleaseChecker, ...
 @dimina-kit/devtools/launch                 launch(config?), buildDefaultMenu, openSettingsWindow
 @dimina-kit/devtools/types                  TypeScript 类型定义
 @dimina-kit/devtools/bootstrap              suppressEpipe(), setupCdpPort()
-@dimina-kit/devtools/context                createWorkbenchContext(opts),
-                                       hasBuiltinPanel(ctx, panelId), getDefaultTab(ctx)
+@dimina-kit/devtools/context                createWorkbenchContext(opts)
 @dimina-kit/devtools/create-window          createMainWindow(opts)
 @dimina-kit/devtools/paths                  rendererDir, defaultPreloadPath, simulatorDir,
                                        getRendererDir, getPreloadDir, getRendererHtml
@@ -527,19 +543,32 @@ launch({
 
 ---
 
+## MiniappRuntime（宿主集成推荐契约）
+
+下游宿主（如 qdmp）集成时，推荐依赖手写的稳定契约 `MiniappRuntime`，而不是整个 `WorkbenchContext`——后者携带全部内部 service 类型，内部重构会直接破坏下游编译。`asMiniappRuntime(ctx)` 恒等返回（typed view，非拷贝），宿主对 `runtime.workspace.openProject` 的 monkey-patch 会落在真实对象上：
+
+```typescript
+import { asMiniappRuntime, type MiniappRuntime } from '@dimina-kit/devtools'
+
+const runtime: MiniappRuntime = asMiniappRuntime(instance.context)
+runtime.workspace.openProject = gated(runtime.workspace.openProject) // 权限闸（契约保证可写）
+runtime.views.hostToolbar.send('host:cmd', { theme: 'dark' })
+runtime.notify.projectStatus({ status: 'ready', message: '编译完成' })
+```
+
+契约面：`rendererDir` / `views.hostToolbar`（6 成员，无 `webContents`）/ `workspace`（7 方法）/ `notify.projectStatus` / `registry.add` / `windows`（不透明句柄）。零 Electron 类型。
+
 ## WorkbenchContext
 
-`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是收窄后的 `MenuContext`（剔除 `registry` / `senderPolicy` / `trustedWindowSenderIds` / `simulatorApis` / `toolbar` 等内部管线）。
+`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是收窄后的 `MenuContext`（剔除 `registry` / `senderPolicy` / `trustedWindowSenderIds` / `simulatorApis` 等内部管线）。
 
 ```typescript
 interface WorkbenchContext {
   adapter: CompilationAdapter
   preloadPath: string
   rendererDir: string
-  panels: string[]
   apiNamespaces: string[]
   appName: string
-  headerHeight: number
   brandingProvider?: () => Promise<{ appName: string }> | { appName: string }
 
   // ── Services（运行时状态封装在内部，通过方法访问）──
@@ -550,7 +579,6 @@ interface WorkbenchContext {
 
   // ── 扩展容器（host 通过 instance 上的方法写入，不直接操作）──
   simulatorApis: SimulatorApiRegistry  // instance.registerSimulatorApi 写入
-  toolbar: ToolbarStore                // instance.toolbar.set 写入
   trustedWindowSenderIds: Map<number, number>  // instance.registerTrustedWindow 写入（webContents.id → 引用计数）
 
   // ── Internal lifecycle / security (host 不直接消费) ──
@@ -562,7 +590,7 @@ interface WorkbenchContext {
 会话和视图状态封装在对应 service 的私有闭包中，通过方法访问，例如：
 
 - `ctx.workspace.getProjectPath()` / `ctx.workspace.getSession()` / `ctx.workspace.hasActiveSession()`
-- `ctx.views.getSimulatorWebContentsId()` / `ctx.views.isSimulatorAdded()` / `ctx.views.getLastSimWidth()`
+- `ctx.views.getSimulatorWebContentsId()` / `ctx.views.getSimulatorWebContents()`
 - `ctx.windows.mainWindow` / `ctx.windows.settingsWindow`
 
 ---
@@ -604,13 +632,11 @@ flowchart TB
 | Storage | 拉取 + 推送 | renderer `ipcInvoke(SimulatorStorageChannel.GetSnapshot)` → 主进程 CDP `DOMStorage` 域；变更事件由主进程通过 `SimulatorStorageChannel.Event` 推回 renderer |
 | 元素选区 / `Page.getData` / MCP overview | 拉取 | 主进程 `webContents.executeJavaScript(...)` 或 `Runtime.evaluate(...)` 读 `window.__simulatorData.*`（由 `installSimulatorBridge` 暴露） |
 
-> `src/main/ipc/panels.ts` 暴露 `panel:eval` handler 供外部 host 自定义面板复用，内置 renderer 不消费它。
-
 ---
 
 ## IPC 通信总览
 
-IPC 频道名常量集中定义在 `src/shared/ipc-channels.ts`，按域分组（`SimulatorChannel` / `ProjectChannel` / `PanelChannel` / `WorkbenchSettingsChannel` 等）。该文件是频道清单的唯一真相源；此处不再维护手抄表，以免与代码漂移。
+IPC 频道名常量集中定义在 `src/shared/ipc-channels.ts`，按域分组（`SimulatorChannel` / `ProjectChannel` / `WorkbenchSettingsChannel` 等）。该文件是频道清单的唯一真相源；此处不再维护手抄表，以免与代码漂移。
 
 ---
 
@@ -620,7 +646,7 @@ 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 中渲染，数据由主进程服务直接供给——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`。
+**当前方案**：内置面板（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/simulator.ts`。
 
 ---
 

package/dist/main/api.d.ts

@@ -1,7 +1,9 @@
 export { launch, buildDefaultMenu, openSettingsWindow } from './app/launch.js';
 export type { WorkbenchAppInstance } from './app/app.js';
 export { suppressEpipe, setupCdpPort } from './app/bootstrap.js';
-export { createWorkbenchContext, hasBuiltinPanel, getDefaultTab } from './services/workbench-context.js';
+export { asMiniappRuntime } from './runtime/miniapp-runtime.js';
+export type { MiniappRuntime } from './runtime/miniapp-runtime.js';
+export { createWorkbenchContext } from './services/workbench-context.js';
 export type { WorkbenchContext, CreateContextOptions } from './services/workbench-context.js';
 export { createMainWindow } from './windows/main-window/index.js';
 export { createViewManager } from './services/views/view-manager.js';
@@ -14,5 +16,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 { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, ToolbarAction, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
+export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
 //# sourceMappingURL=api.d.ts.map

package/dist/main/api.js

@@ -7,8 +7,12 @@
 export { launch, buildDefaultMenu, openSettingsWindow } from './app/launch.js';
 // ── Bootstrap utilities ──────────────────────────────────────────────────
 export { suppressEpipe, setupCdpPort } from './app/bootstrap.js';
+// ── Miniapp runtime contract (host-facing, stable) ───────────────────────
+// The hand-written kernel surface a downstream host consumes; prefer this
+// over depending on the full `WorkbenchContext`.
+export { asMiniappRuntime } from './runtime/miniapp-runtime.js';
 // ── Context & views (for module-assembly consumers) ──────────────────────
-export { createWorkbenchContext, hasBuiltinPanel, getDefaultTab } from './services/workbench-context.js';
+export { createWorkbenchContext } from './services/workbench-context.js';
 export { createMainWindow } from './windows/main-window/index.js';
 export { createViewManager } from './services/views/view-manager.js';
 // ── Paths ────────────────────────────────────────────────────────────────

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

@@ -1,5 +1,5 @@
 import { BrowserWindow } from 'electron';
-import type { ToolbarActionInput, WorkbenchAppConfig } from '../../shared/types.js';
+import type { WorkbenchAppConfig } from '../../shared/types.js';
 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';
@@ -15,10 +15,6 @@ export interface WorkbenchAppInstance {
     registerTrustedWindow: (win: BrowserWindow) => Disposable;
     /** Registers a simulator custom API into this context's registry. */
     registerSimulatorApi: (name: string, handler: SimulatorApiHandler) => Disposable;
-    /** Per-context toolbar surface — `set()` atomically replaces the table. */
-    readonly toolbar: {
-        set(actions: ToolbarActionInput[]): void;
-    };
     automationServer?: AutomationServer;
     updateManager?: UpdateManager;
     dispose: () => Promise<void>;

package/dist/main/app/app.js

@@ -145,10 +145,8 @@ function createContext(config, mainWindow, rendererDir) {
         adapter: config.adapter,
         preloadPath: config.preloadPath ?? defaultPreloadPath,
         rendererDir,
-        panels: config.panels,
         appName: config.appName,
         apiNamespaces: config.apiNamespaces,
-        headerHeight: config.headerHeight,
         brandingProvider: config.brandingProvider,
         // The host-supplied ProjectsProvider / template types in `shared/types`
         // are structurally compatible with the main-process equivalents —
@@ -169,7 +167,7 @@ function registerBuiltinModules(config, context) {
 }
 /**
  * Strip the internal-plumbing fields a host menu builder must not reach
- * (registry / senderPolicy / trustedWindowSenderIds / simulatorApis / toolbar)
+ * (registry / senderPolicy / trustedWindowSenderIds / simulatorApis)
  * so `menuBuilder` receives the narrowed `MenuContext` its contract promises —
  * at runtime, not just at the type level.
  */
@@ -181,7 +179,6 @@ function toMenuContext(context) {
     delete menuContext.senderPolicy;
     delete menuContext.trustedWindowSenderIds;
     delete menuContext.simulatorApis;
-    delete menuContext.toolbar;
     return menuContext;
 }
 function installMenu(config, mainWindow, context) {
@@ -345,15 +342,6 @@ export async function createDevtoolsRuntime(config = {}) {
         // teardown, so a single dispose leaves no dead entry behind.
         registerTrustedWindow: (win) => context.registry.add(registerTrustedWindow(context, win)),
         registerSimulatorApi: (name, handler) => context.registry.add(toDisposable(context.simulatorApis.register(name, handler))),
-        toolbar: {
-            set: (actions) => {
-                // `context.toolbar.set` validates id-uniqueness and throws on a
-                // duplicate BEFORE mutating, so a rejected batch never reaches
-                // the notify below — no phantom ActionsChanged.
-                context.toolbar.set(actions);
-                context.notify.toolbarActionsChanged();
-            },
-        },
         dispose: () => disposeContext(context),
     };
     if (config.onSetup) {
@@ -470,9 +458,9 @@ export async function createDevtoolsRuntime(config = {}) {
         // upload run there, not in the service host) in the embedded DevTools by
         // injecting its raw Network.* CDP events into the DevTools front-end so the
         // native Network tab renders them (service-host console line is the
-        // fallback). The ViewManager calls attachSimulator + setDevtoolsHost from
-        // attachNativeSimulator once the simulator WCV + DevTools host exist;
-        // getServiceWc here is the fallback sink target.
+        // fallback). The ViewManager calls the forwarder's attachSimulator +
+        // setDevtoolsHost from attachNativeSimulator once the simulator WCV +
+        // DevTools host exist; getServiceWc here is the fallback sink target.
         const networkForward = createNetworkForwarder({
             getServiceWc: (appId) => context.bridge?.getServiceWc(appId) ?? null,
             connections: context.connections,