@dimina-kit/devtools 0.4.0-dev.20260728110120 → 0.4.0-dev.20260731100034

package/README.md

@@ -53,6 +53,13 @@ launch({
     // simulator 自定义 API：per-context
     instance.registerSimulatorApi('login', (params) => myLogin(params))
 
+    // simulator 下游 UI：框架管理 DeviceShell 挂载点与生命周期
+    const nativeUi = instance.registerSimulatorUiExtension({
+      id: 'my.native-ui',
+      rendererScriptPath: '/absolute/path/to/native-ui.js',
+    })
+    instance.registerSimulatorApi('share', params => nativeUi.invoke('share', params))
+
     // 自定义 IPC：经 gated 的 IpcRegistry，不再裸 ipcMain.handle
     instance.ipc.handle('my:action', () => collectStats())
 
@@ -207,6 +214,7 @@ src/
 | 方法 | 说明 |
 | --- | --- |
 | `instance.registerSimulatorApi(name, handler)` | 注册 simulator 自定义 API，小程序里 `wx.<name>()` 调用（详见下方"Simulator 自定义 API"）。返回 `Disposable` |
+| `instance.registerSimulatorUiExtension({ id, rendererScriptPath })` | 注册可信 renderer bundle。框架负责注入当前 simulator、稳定 Overlay Root、soft reload 的 current/pending 切换和销毁；返回可 `invoke()` 的句柄 |
 | `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
 | `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
 
@@ -482,6 +490,66 @@ launch({
 
 ---
 
+## Simulator UI 扩展
+
+需要分享面板、授权弹窗等产品 UI 的下游 host，应同时使用两个正交接口：
+
+- `registerSimulatorApi` 定义小程序侧 `wx.*` 命令。
+- `registerSimulatorUiExtension` 安装下游 renderer bundle，并通过返回句柄把命令送到 UI。
+
+主进程只注册绝对路径指向的可信构建产物：
+
+```typescript
+const nativeUi = instance.registerSimulatorUiExtension({
+  id: 'my.native-ui',
+  rendererScriptPath: fileURLToPath(
+    new URL('../renderer/native-ui.js', import.meta.url),
+  ),
+})
+
+instance.registerSimulatorApi('share', params =>
+  nativeUi.invoke('share', params),
+)
+```
+
+renderer bundle 使用 `@dimina-kit/devtools/simulator-ui` 注册实现：
+
+```typescript
+import { registerSimulatorUiExtension } from '@dimina-kit/devtools/simulator-ui'
+
+let runtime
+
+registerSimulatorUiExtension({
+  id: 'my.native-ui',
+  mount({ overlayRoot, appId, signal }) {
+    runtime = createNativeUi({ root: overlayRoot, appId })
+    signal.addEventListener('abort', () => runtime.destroy(), { once: true })
+    return () => runtime.destroy()
+  },
+  invoke(method, params) {
+    return runtime.invoke(method, params)
+  },
+  onChromeAction(action) {
+    if (action.name !== 'capsule.more') return false
+    runtime.showMoreMenu(action)
+    return true
+  },
+})
+```
+
+契约边界：
+
+- 框架只提供设备内的稳定 Overlay Root，不接收 React Component，因而不绑定下游 React 版本。
+- 只有可见的 current `DeviceShell` 持有挂载点；soft reload 提升 pending shell 时，旧 mount 先收到 abort/cleanup，再在新 root 上 mount。
+- Overlay Root 默认不拦截页面点击；扩展实际创建的交互层需要设置 `pointer-events: auto`。
+- 胶囊菜单通过语义动作 `capsule.more` 分发，不应查询 `.menu-capsule__more` 或拦截 DOM click。
+- `id` 在一个 context 内唯一；script 必须用相同 `id` 注册 renderer 实现，否则安装失败。
+- 每次 simulator 顶层文档完成加载时都会重新读取 `rendererScriptPath`，因此开发态重建
+  bundle 后执行硬 reload 即可加载新代码；soft reload 只切换 DeviceShell 挂载点，不重复执行 bundle。
+- `dispose()` 会注销 renderer 实现；context 销毁时自动执行。`invoke()` 参数和返回值必须可跨 Electron IPC/`executeJavaScript` 序列化。
+
+---
+
 ## Host Toolbar（宿主自定义工具栏）
 
 下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素；`{ fixed }` 校验入参——非有限数或负数同步抛 `TypeError` 且不污染既有模式）。主进程保留最后一次下发的高度（`views.getHostToolbarHeight()`），项目视图的占位条挂载时会主动拉取并回放——广播器对已上报的高度去重不再重发，没有这一步，冷启动在项目列表期间的上报、以及关闭项目再打开后的高度都会永久丢失（工具栏条塌缩为 0）。

package/dist/main/api.d.ts

@@ -11,6 +11,7 @@ export type { ViewManager } from './services/views/view-manager.js';
 export type { WorkspaceService } from './services/workspace/workspace-service.js';
 export type { Project, ProjectPages, ProjectSettings } from './services/projects/project-repository.js';
 export type { SimulatorApiHandler } from './services/simulator/custom-apis.js';
+export type { SimulatorUiExtensionHandle, SimulatorUiExtensionRegistration, } from '../shared/simulator-ui.js';
 export { rendererDir, defaultPreloadPath, simulatorDir, getRendererDir, getPreloadDir, getRendererHtml, } from './utils/paths.js';
 export { IpcRegistry } from './utils/ipc-registry.js';
 export type { SenderPolicy } from './utils/ipc-registry.js';

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

@@ -1,5 +1,6 @@
 import { BrowserWindow } from 'electron';
 import type { WorkbenchAppConfig } from '../../shared/types.js';
+import type { SimulatorUiExtensionHandle, SimulatorUiExtensionRegistration } from '../../shared/simulator-ui.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,6 +16,8 @@ export interface WorkbenchAppInstance {
     registerTrustedWindow: (win: BrowserWindow) => Disposable;
     /** Registers a simulator custom API into this context's registry. */
     registerSimulatorApi: (name: string, handler: SimulatorApiHandler) => Disposable;
+    /** Registers a downstream renderer extension for the simulator device UI. */
+    registerSimulatorUiExtension: (registration: SimulatorUiExtensionRegistration) => SimulatorUiExtensionHandle;
     automationServer?: AutomationServer;
     updateManager?: UpdateManager;
     dispose: () => Promise<void>;

package/dist/main/app/app.js

@@ -476,6 +476,14 @@ onInstanceCreated) {
         // 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))),
+        registerSimulatorUiExtension: (registration) => {
+            const extension = context.simulatorUiExtensions.register(registration);
+            const owned = context.registry.add(extension);
+            return {
+                dispose: () => owned.dispose(),
+                invoke: (method, params) => extension.invoke(method, params),
+            };
+        },
         dispose: () => disposeContext(context),
     };
     onInstanceCreated?.(instance);
@@ -614,6 +622,13 @@ onInstanceCreated) {
         context.registry.add(toDisposable(context.internalDevtoolsWindow?.onHostChanged((hostWc) => {
             context.networkForward?.setGlobalDevtoolsHost(hostWc);
         }) ?? (() => { })));
+        // Main-process WebSocket traffic (wx.connectSocket runs on the Node `ws`
+        // transport, invisible to any webContents debugger): bridge-router fans
+        // the trace stream out here, and the forwarder synthesizes it into
+        // Network.webSocket* CDP events for the same Network panel sinks.
+        context.registry.add(toDisposable(context.bridge?.onNativeWebSocketTrace?.((ownerId, event) => {
+            context.networkForward?.reportWebSocketTrace(ownerId, event);
+        }) ?? (() => { })));
         context.registry.add(setupSimulatorWxml(mainWindow.webContents, {
             senderPolicy: context.senderPolicy,
             bridge: context.bridge,

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

@@ -1,10 +1,13 @@
 /**
- * Register `difile://` as a privileged scheme so `simSession.protocol.handle`
- * can serve `difile://devtools/{uuid}` URLs from the simulator webview without
- * tripping CSP / fetch-API restrictions. Must be called before `app.whenReady`.
+ * Register privileged custom schemes before `app.whenReady`.
  *
- * Idempotent — subsequent calls are no-ops because Electron throws if the same
- * scheme is registered twice.
+ * Electron allows only one process-global `registerSchemesAsPrivileged` call, so
+ * this merges the runtime's `difile` + `dmb-resource` descriptors (required for
+ * render-host documents / ES module fetches on `dmb-resource://`) and keeps
+ * `bypassCSP` on `difile` for the simulator temp-file path.
+ *
+ * Idempotent — subsequent calls are no-ops because Electron throws if schemes
+ * are registered twice.
  */
 export declare function registerDifileScheme(): void;
 /**

package/dist/main/app/bootstrap.js

@@ -1,32 +1,32 @@
 import { app, protocol } from 'electron';
+import { ELECTRON_RUNTIME_SCHEMES } from '@dimina-kit/electron-runtime';
 import { DEFAULT_CDP_PORT } from '../../shared/constants.js';
 import { loadWorkbenchSettings } from '../services/settings/index.js';
 let difileSchemeRegistered = false;
 /**
- * Register `difile://` as a privileged scheme so `simSession.protocol.handle`
- * can serve `difile://devtools/{uuid}` URLs from the simulator webview without
- * tripping CSP / fetch-API restrictions. Must be called before `app.whenReady`.
+ * Register privileged custom schemes before `app.whenReady`.
  *
- * Idempotent — subsequent calls are no-ops because Electron throws if the same
- * scheme is registered twice.
+ * Electron allows only one process-global `registerSchemesAsPrivileged` call, so
+ * this merges the runtime's `difile` + `dmb-resource` descriptors (required for
+ * render-host documents / ES module fetches on `dmb-resource://`) and keeps
+ * `bypassCSP` on `difile` for the simulator temp-file path.
+ *
+ * Idempotent — subsequent calls are no-ops because Electron throws if schemes
+ * are registered twice.
  */
 export function registerDifileScheme() {
     if (difileSchemeRegistered)
         return;
     difileSchemeRegistered = true;
-    protocol.registerSchemesAsPrivileged([
-        {
-            scheme: 'difile',
+    protocol.registerSchemesAsPrivileged(ELECTRON_RUNTIME_SCHEMES.map((entry) => (entry.scheme === 'difile'
+        ? {
+            scheme: entry.scheme,
             privileges: {
-                standard: true,
-                secure: true,
-                supportFetchAPI: true,
-                stream: true,
+                ...entry.privileges,
                 bypassCSP: true,
-                corsEnabled: true,
             },
-        },
-    ]);
+        }
+        : { scheme: entry.scheme, privileges: { ...entry.privileges } })));
 }
 /**
  * Suppress EPIPE errors on stdout/stderr.