@dimina-kit/devtools 0.3.2-dev.20260611135124 → 0.4.0-dev.20260612152115

package/README.md

@@ -1,6 +1,6 @@
 # Dimina DevTools
 
-基于 Electron 的小程序开发者工具。提供模拟器、Chrome DevTools 面板、WXML/AppData/Storage 面板、编译配置等功能。
+基于 Electron 的小程序开发者工具。提供模拟器、Chrome DevTools 面板、WXML/AppData/Storage/编译 面板、编译配置等功能。
 
 下游 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)）。
 
@@ -147,7 +147,7 @@ src/
         main.tsx                         # 主窗口 React 根
         features/                        # 主窗口内的业务区域
           project-runtime/               # 项目视图 + 工具栏 + 右侧面板切换
-          right-panel/                   # WXML / AppData / Storage 面板
+          right-panel/                   # WXML / AppData / Storage / 编译 面板
       popover/ settings/ workbench-settings/
     shared/
       components/                        # UI 组件（ui / layout / json-viewer / ...）
@@ -177,7 +177,7 @@ src/
 | ------------------ | -------------------- | ------------------- | ---------------------------------- |
 | `appName`          | `string`             | `'Dimina DevTools'` | 窗口标题                           |
 | `adapter`          | `CompilationAdapter` | 内置                | 项目编译适配器                     |
-| `panels`           | `BuiltinPanelId[]`   | —                   | **已废弃，运行时忽略**：界面恒显示全部四个内置面板；保留字段仅为兼容仍传它的 host |
+| `panels`           | `BuiltinPanelId[]`   | —                   | **已废弃，运行时忽略**：界面恒显示全部内置面板（WXML / AppData / Storage / Console / 编译）；保留字段仅为兼容仍传它的 host |
 | `preloadPath`      | `string`             | 内置                | 统一的 host 级 preload 入口；native-host simulator（WCV）自动跑其 `.cjs` sibling（`cjsSiblingPreloadPath`） |
 | `apiNamespaces`    | `string[]`           | `[]`                | 自定义 API 命名空间（如 `['qd']`） |
 | `brandingProvider` | `() => { appName }`  | —                   | 品牌信息 provider                  |
@@ -192,7 +192,7 @@ 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` 等内部管线 |
+| `menuBuilder`   | `(mainWindow, menuContext: MenuContext) => void` | 内置菜单 | 自定义菜单构建器；`menuContext` 为手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`），不含内部管线 |
 | `onSetup`       | `(instance) => void`                        | —           | 窗口和 context 创建后的回调，用于注册 Contribution（见下文）|
 | `onBeforeClose` | `(instance) => void`                        | —           | 窗口关闭前的回调，session 关闭由框架自动处理      |
 | `window`        | `WorkbenchWindowConfig`                     | —           | 窗口尺寸覆盖                                      |
@@ -483,7 +483,7 @@ launch({
 
 ## Host Toolbar（宿主自定义工具栏）
 
-下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素）。
+下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素；`{ fixed }` 校验入参——非有限数或负数同步抛 `TypeError` 且不污染既有模式）。主进程保留最后一次下发的高度（`views.getHostToolbarHeight()`），项目视图的占位条挂载时会主动拉取并回放——广播器对已上报的高度去重不再重发，没有这一步，冷启动在项目列表期间的上报、以及关闭项目再打开后的高度都会永久丢失（工具栏条塌缩为 0）。
 
 ### 双向消息：onMessage / send
 
@@ -491,8 +491,9 @@ launch({
 
 - `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 }` 两个函数；握手前的 `send` 进队列、握手后按序送达。队列上限 128 条：超限丢弃最新一条、首次超限 console.warn 一次，不抛错）：
+页面侧由框架自动注入 `window.diminaHostToolbar`（仅 `{ send, onMessage }` 两个函数；类型可从根入口导入 `DiminaHostToolbarPageBridge`，并附带 optional 的 `Window` 增强。握手前的 `send` 进队列、握手后按序送达。队列上限 128 条：超限丢弃最新一条、首次超限 console.warn 一次，不抛错。`send`/`onMessage` 对空串/非 string channel 同步抛 `TypeError`，与主进程同语义）：
 
 ```js
 // 工具栏页面内
@@ -515,7 +516,8 @@ instance.context.views.hostToolbar.send('host:cmd', { theme: 'dark' }) // false
 ```
 @dimina-kit/devtools                        launch, buildDefaultMenu,
                                        openSettingsWindow, suppressEpipe, setupCdpPort,
-                                       asMiniappRuntime, MiniappRuntime（type）,
+                                       asMiniappRuntime, MiniappRuntime / MiniappSessionAppInfo /
+                                       DiminaHostToolbarPageBridge（type）,
                                        createWorkbenchContext, createMainWindow,
                                        createViewManager, IpcRegistry,
                                        UpdateManager, createGitHubReleaseChecker, ...
@@ -556,11 +558,11 @@ 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 类型。
+契约面：`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` 等内部管线）。
+`WorkbenchContext` 是所有扩展点的唯一容器。配置字段直接暴露，运行时状态通过 service 访问。host hook 拿到的 `instance.context` 即此类型；`menuBuilder` 拿到的是手写窄契约 `MenuContext`（`appName` + workspace 窄集 + `openSettings` + `notify.{projectStatus, windowNavigateBack}`，不再是 `WorkbenchContext` 的 Omit 投影）。
 
 ```typescript
 interface WorkbenchContext {

package/dist/main/api.d.ts

@@ -2,7 +2,7 @@ export { launch, buildDefaultMenu, openSettingsWindow } from './app/launch.js';
 export type { WorkbenchAppInstance } from './app/app.js';
 export { suppressEpipe, setupCdpPort } from './app/bootstrap.js';
 export { asMiniappRuntime } from './runtime/miniapp-runtime.js';
-export type { MiniappRuntime } 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';

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';
@@ -166,20 +167,29 @@ function registerBuiltinModules(config, context) {
     });
 }
 /**
- * Strip the internal-plumbing fields a host menu builder must not reach
- * (registry / senderPolicy / trustedWindowSenderIds / simulatorApis)
- * 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;
-    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

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