@dimina-kit/devtools 0.3.2-dev.20260611063505 → 0.4.0-dev.20260612025610

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,17 +53,6 @@ launch({
     // simulator 自定义 API：per-context
     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() },
-      ])
-    }
-    refreshToolbar()
-
     // 自定义 IPC：经 gated 的 IpcRegistry，不再裸 ipcMain.handle
     instance.ipc.handle('my:action', () => collectStats())
 
@@ -72,12 +60,6 @@ launch({
     // 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 销毁由框架自动处理
   },
@@ -105,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                        # 项目列表管理
@@ -197,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）
 
@@ -212,10 +192,9 @@ src/
 | `modules`       | `Partial<Record<BuiltinModuleId, boolean>>` | 全部 `true` | 开关内置 IPC 模块组                               |
 | `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 关闭由框架自动处理      |
+| `menuBuilder`   | `(mainWindow, menuContext: MenuContext) => void` | 内置菜单 | 自定义菜单构建器；`menuContext` 为手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`），不含内部管线 |
+| `onSetup`       | `(instance) => void`                        | —           | 窗口和 context 创建后的回调，用于注册 Contribution（见下文）|
+| `onBeforeClose` | `(instance) => void`                        | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
 | `window`        | `WorkbenchWindowConfig`                     | —           | 窗口尺寸覆盖                                      |
 | `updateChecker` | `UpdateChecker`                             | —           | 自定义更新检查器；提供后启用"检查更新"功能        |
 | `updateOptions` | `{ checkInterval?, initialDelay?, getCurrentVersion? }` | —  | 仅当 `updateChecker` 提供时生效，默认 1h / 5s     |
@@ -227,12 +206,9 @@ 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` 调用会被网关拒绝。窗口关闭即移除 |
 
-`onSetup` 可以返回 Promise；`createWorkbenchApp().start()` 会等待 `onSetup` 解析完成后才继续后续启动流程，因此宿主在 `onSetup` 内注册的 simulator API 会早于 simulator `<webview>` 首次枚举自定义 API。
-
 ### 内置面板 ID
 
 `'wxml'` \| `'console'` \| `'appdata'` \| `'storage'`
@@ -505,6 +481,34 @@ launch({
 
 ---
 
+## Host Toolbar（宿主自定义工具栏）
+
+下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素；`{ fixed }` 校验入参——非有限数或负数同步抛 `TypeError` 且不污染既有模式）。
+
+### 双向消息：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 保留）。
+- `hostToolbar.onReady(handler): { dispose() }` — 握手完成的推送信号（每个 load generation fire 一次；已就绪后注册在微任务上补发一次，补发前复查订阅与 generation）。在 handler 内 `send()` 必然返回 `true`，可用于推送初始状态，替代轮询 retry loop。
+
+页面侧由框架自动注入 `window.diminaHostToolbar`（仅 `{ send, onMessage }` 两个函数；类型可从根入口导入 `DiminaHostToolbarPageBridge`，并附带 optional 的 `Window` 增强。握手前的 `send` 进队列、握手后按序送达。队列上限 128 条：超限丢弃最新一条、首次超限 console.warn 一次，不抛错。`send`/`onMessage` 对空串/非 string channel 同步抛 `TypeError`，与主进程同语义）：
+
+```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，优先从根入口导入。
@@ -512,14 +516,15 @@ launch({
 ```
 @dimina-kit/devtools                        launch, buildDefaultMenu,
                                        openSettingsWindow, suppressEpipe, setupCdpPort,
+                                       asMiniappRuntime, MiniappRuntime / MiniappSessionAppInfo /
+                                       DiminaHostToolbarPageBridge（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
@@ -540,19 +545,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: '编译完成' })
+```
+
+契约面：`views.hostToolbar`（7 成员，含 `onReady`，无 `webContents`）/ `workspace`（7 方法，`getSession().appInfo` 为结构化 `MiniappSessionAppInfo`，`appId` 必有）/ `notify.projectStatus` / `registry.add`（接受 `{ dispose }` 对象或裸函数两种习语）/ `openSettings()`。零 Electron 类型。0.4.0 起不再含 `rendererDir`（用 `/paths` 导出）与 `windows`（用 `openSettings()`）。
+
 ## WorkbenchContext
 
-`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是收窄后的 `MenuContext`（剔除 `registry` / `senderPolicy` / `trustedWindowSenderIds` / `simulatorApis` / `toolbar` 等内部管线）。
+`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`，不再是 `WorkbenchContext` 的 Omit 投影）。
 
 ```typescript
 interface WorkbenchContext {
   adapter: CompilationAdapter
   preloadPath: string
   rendererDir: string
-  panels: string[]
   apiNamespaces: string[]
   appName: string
-  headerHeight: number
   brandingProvider?: () => Promise<{ appName: string }> | { appName: string }
 
   // ── Services（运行时状态封装在内部，通过方法访问）──
@@ -563,7 +581,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 不直接消费) ──
@@ -575,7 +592,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`
 
 ---
@@ -617,13 +634,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` 等）。该文件是频道清单的唯一真相源；此处不再维护手抄表，以免与代码漂移。
 
 ---
 
@@ -633,7 +648,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, MiniappSessionAppInfo, DiminaHostToolbarPageBridge, } 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 { BeforeOpenProjectHook, BeforeOpenProjectResult, WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, ToolbarAction, ToolbarActionInput, ToolbarActionKind, ToolbarActionPlacement, 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

@@ -6,6 +6,7 @@ import path from 'path';
 import { rendererDir as defaultRendererDir, defaultPreloadPath } from '../utils/paths.js';
 import { installThemeBackgroundSync } from '../utils/theme.js';
 import { createMainWindow, wireMainWindowEvents } from '../windows/main-window/index.js';
+// eslint-disable-next-line no-restricted-syntax -- grandfathered(workbench-context): shrink-only
 import { createWorkbenchContext } from '../services/workbench-context.js';
 import { loadWorkbenchSettings, applyTheme } from '../services/settings/index.js';
 import { installAppMenu } from '../menu/index.js';
@@ -145,10 +146,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 —
@@ -168,21 +167,29 @@ function registerBuiltinModules(config, context) {
     });
 }
 /**
- * Strip the internal-plumbing fields a host menu builder must not reach
- * (registry / senderPolicy / trustedWindowSenderIds / simulatorApis / toolbar)
- * so `menuBuilder` receives the narrowed `MenuContext` its contract promises —
- * at runtime, not just at the type level.
+ * Build the hand-written narrow `MenuContext` a host menu builder receives —
+ * explicit construction (not clone+delete), so the runtime object carries
+ * EXACTLY the contract members and nothing else. Every member is a lazy
+ * closure over the live context: a host monkey-patch of
+ * `context.workspace.openProject` (the documented permission-gate pattern)
+ * still intercepts calls made through this menu surface.
  */
 function toMenuContext(context) {
-    // Shallow-copy, then drop the internal-plumbing fields. A rest-destructure
-    // would be terser but trips no-unused-vars on the dropped siblings.
-    const menuContext = { ...context };
-    delete menuContext.registry;
-    delete menuContext.senderPolicy;
-    delete menuContext.trustedWindowSenderIds;
-    delete menuContext.simulatorApis;
-    delete menuContext.toolbar;
-    return menuContext;
+    return {
+        appName: context.appName,
+        workspace: {
+            hasActiveSession: () => context.workspace.hasActiveSession(),
+            getProjectPath: () => context.workspace.getProjectPath(),
+            openProject: (projectPath) => context.workspace.openProject(projectPath),
+            closeProject: () => context.workspace.closeProject(),
+            getSession: () => context.workspace.getSession(),
+        },
+        openSettings: () => context.openSettings(),
+        notify: {
+            projectStatus: (payload) => context.notify.projectStatus(payload),
+            windowNavigateBack: () => context.notify.windowNavigateBack(),
+        },
+    };
 }
 function installMenu(config, mainWindow, context) {
     // Menu: use host-provided builder or fall back to default
@@ -345,20 +352,8 @@ 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.onBeforeOpenProject) {
-        context.beforeOpenProject = (projectPath) => config.onBeforeOpenProject({ projectPath, instance });
-    }
     if (config.onSetup) {
         await config.onSetup(instance);
     }
@@ -473,9 +468,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,

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

@@ -1,5 +1,4 @@
-import type { WorkbenchAppConfig } from '../../shared/types.js';
-import type { WorkbenchContext } from '../services/workbench-context.js';
+import type { MenuContext, WorkbenchAppConfig } from '../../shared/types.js';
 /**
  * Host-shell entry for the devtools app. Boots through the
  * `@dimina-kit/electron-deck` framework orchestrator (process lifecycle gate +
@@ -9,6 +8,7 @@ import type { WorkbenchContext } from '../services/workbench-context.js';
  * passing `WorkbenchAppConfig` (incl. `onSetup`, `apiNamespaces`, `menuBuilder`, …).
  */
 export declare function launch(config?: WorkbenchAppConfig): Promise<void>;
-export declare function buildDefaultMenu(ctx: WorkbenchContext): void;
-export declare function openSettingsWindow(ctx: Pick<WorkbenchContext, 'rendererDir' | 'notify' | 'windows'>): Promise<void>;
+export declare function buildDefaultMenu(ctx: MenuContext): void;
+export { openSettingsWindow } from '../windows/settings-window/index.js';
+export type { OpenSettingsWindowDeps } from '../windows/settings-window/index.js';
 //# sourceMappingURL=launch.d.ts.map

package/dist/main/app/launch.js

@@ -1,8 +1,6 @@
 import { electronDeck as frameworkElectronDeck } from '@dimina-kit/electron-deck';
 import { createDevtoolsBackend } from '../runtime/devtools-backend.js';
 import { installAppMenu } from '../menu/index.js';
-import { createSettingsWindow, wireSettingsWindowEvents } from '../windows/settings-window/index.js';
-import { loadWorkbenchSettings } from '../services/settings/index.js';
 /**
  * Host-shell entry for the devtools app. Boots through the
  * `@dimina-kit/electron-deck` framework orchestrator (process lifecycle gate +
@@ -17,19 +15,9 @@ export function launch(config = {}) {
 export function buildDefaultMenu(ctx) {
     installAppMenu(ctx);
 }
-export async function openSettingsWindow(ctx) {
-    let win = ctx.windows.settingsWindow;
-    if (!win || win.isDestroyed()) {
-        win = await createSettingsWindow(ctx.windows.mainWindow, ctx.rendererDir);
-        ctx.windows.setSettingsWindow(win);
-        wireSettingsWindowEvents(win, () => {
-            ctx.windows.setSettingsWindow(null);
-        });
-    }
-    win.show();
-    win.focus();
-    ctx.notify.workbenchSettingsInit(win, {
-        settings: loadWorkbenchSettings(),
-    });
-}
+// The implementation lives with the settings-window domain module and takes
+// its own narrow `OpenSettingsWindowDeps` (a full WorkbenchContext satisfies
+// it structurally). Re-exported here so the public barrel path is unchanged.
+// Contract holders should prefer `ctx.openSettings()` / `runtime.openSettings()`.
+export { openSettingsWindow } from '../windows/settings-window/index.js';
 //# sourceMappingURL=launch.js.map