@dimina-kit/devtools 0.4.0-dev.20260728095034 → 0.4.0-dev.20260729062524

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);

package/dist/main/index.bundle.js

@@ -5305,6 +5305,7 @@ function createNativeSimulatorView(ctx, reconciler, deps) {
   }
   function tearDownNativeSimulatorView(label) {
     if (!nativeSimulatorView) return;
+    ctx.simulatorUiExtensions?.detach(nativeSimulatorView.webContents);
     if (nativeSimulatorViewAdded && !ctx.windows.mainWindow.isDestroyed()) {
       try {
         ctx.windows.mainWindow.contentView.removeChildView(nativeSimulatorView);
@@ -5381,6 +5382,7 @@ function createNativeSimulatorView(ctx, reconciler, deps) {
     nativeSimulatorProjectPath = ctx.workspace?.getProjectPath() || null;
     view.setBackgroundColor(simDeskBg());
     const simWc = view.webContents;
+    ctx.simulatorUiExtensions?.attach(simWc);
     const syncDeskBg = () => {
       try {
         if (!simWc.isDestroyed()) view.setBackgroundColor(simDeskBg());
@@ -6192,6 +6194,173 @@ function createLocalProjectsProvider() {
   };
 }
 
+// src/main/services/simulator/ui-extensions.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { pathToFileURL as pathToFileURL2 } from "node:url";
+var EXTENSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function createSimulatorUiExtensionRegistry(options = {}) {
+  const loadSource = options.loadSource ?? ((scriptPath) => readFile2(scriptPath, "utf8"));
+  const entries = /* @__PURE__ */ new Map();
+  let active = null;
+  function assertRegistration(registration) {
+    if (!EXTENSION_ID_RE.test(registration.id)) {
+      throw new Error(`Invalid simulator UI extension id: "${registration.id}"`);
+    }
+    if (!isAbsolute(registration.rendererScriptPath)) {
+      throw new Error("Simulator UI extension rendererScriptPath must be absolute");
+    }
+    if (entries.has(registration.id)) {
+      throw new Error(`Simulator UI extension "${registration.id}" is already registered`);
+    }
+  }
+  function activeExpression(method, args) {
+    return `globalThis.__diminaSimulatorUi.${method}(${args.map((arg) => JSON.stringify(arg)).join(",")})`;
+  }
+  async function install(entry, target) {
+    const { id, rendererScriptPath } = entry.registration;
+    if (target.loaded.has(id)) return;
+    const pending = target.loading.get(id);
+    if (pending) return await pending;
+    const generation = target.generation;
+    const task = (async () => {
+      const source = await loadSource(rendererScriptPath);
+      if (entries.get(id) !== entry || active !== target || target.webContents.isDestroyed() || !target.ready || target.generation !== generation) {
+        throw new Error("Simulator UI extension target is no longer available");
+      }
+      const sourceUrl = pathToFileURL2(rendererScriptPath).href;
+      const wrapped = `(()=>{
+${source}
+;return undefined
+})()
+//# sourceURL=${sourceUrl}`;
+      await target.webContents.executeJavaScript(wrapped, true);
+      if (entries.get(id) !== entry || active !== target || target.webContents.isDestroyed() || !target.ready || target.generation !== generation) {
+        throw new Error("Simulator UI extension target was destroyed during installation");
+      }
+      const registered = await target.webContents.executeJavaScript(
+        `Boolean(globalThis.__diminaSimulatorUi?.has(${JSON.stringify(id)}))`,
+        true
+      );
+      if (!registered) {
+        throw new Error(
+          `Simulator UI extension "${id}" did not register its renderer implementation`
+        );
+      }
+      target.loaded.add(id);
+    })().finally(() => {
+      if (target.loading.get(id) === task) target.loading.delete(id);
+    });
+    target.loading.set(id, task);
+    return await task;
+  }
+  async function installAll(target) {
+    for (const entry of entries.values()) {
+      try {
+        await install(entry, target);
+      } catch (error) {
+        console.warn(
+          `[simulator-ui] failed to install "${entry.registration.id}":`,
+          error instanceof Error ? error.message : String(error)
+        );
+      }
+    }
+  }
+  function uninstall(id, target = active) {
+    if (!target) return;
+    target.loaded.delete(id);
+    target.loading.delete(id);
+    if (!target.ready || target.webContents.isDestroyed()) return;
+    void target.webContents.executeJavaScript(
+      `globalThis.__diminaSimulatorUi?.unregister(${JSON.stringify(id)})`,
+      true
+    ).catch(() => {
+    });
+  }
+  function detach(webContents4) {
+    const target = active;
+    if (!target || webContents4 && target.webContents !== webContents4) return;
+    active = null;
+    if (!target.webContents.isDestroyed()) {
+      target.webContents.removeListener("did-finish-load", target.onLoaded);
+    }
+    target.loaded.clear();
+    target.loading.clear();
+  }
+  function attach(webContents4) {
+    detach();
+    const target = {
+      webContents: webContents4,
+      ready: false,
+      generation: 0,
+      loaded: /* @__PURE__ */ new Set(),
+      loading: /* @__PURE__ */ new Map(),
+      onLoaded: () => {
+      }
+    };
+    target.onLoaded = () => {
+      if (active !== target || webContents4.isDestroyed()) return;
+      target.ready = true;
+      target.generation += 1;
+      target.loaded.clear();
+      target.loading.clear();
+      void installAll(target);
+    };
+    active = target;
+    webContents4.on("did-finish-load", target.onLoaded);
+  }
+  function register(registration) {
+    assertRegistration(registration);
+    const stableRegistration = { ...registration };
+    const entry = {
+      registration: stableRegistration
+    };
+    entries.set(stableRegistration.id, entry);
+    const target = active;
+    if (target?.ready) {
+      void install(entry, target).catch((error) => {
+        console.warn(
+          `[simulator-ui] failed to install "${stableRegistration.id}":`,
+          error instanceof Error ? error.message : String(error)
+        );
+      });
+    }
+    let disposed = false;
+    return {
+      dispose() {
+        if (disposed) return;
+        disposed = true;
+        if (entries.get(stableRegistration.id) !== entry) return;
+        entries.delete(stableRegistration.id);
+        uninstall(stableRegistration.id);
+      },
+      async invoke(method, params) {
+        if (disposed || entries.get(stableRegistration.id) !== entry) {
+          throw new Error(`Simulator UI extension "${stableRegistration.id}" is disposed`);
+        }
+        const current = active;
+        if (!current || current.webContents.isDestroyed() || !current.ready) {
+          throw new Error("Dimina simulator UI is not ready");
+        }
+        await install(entry, current);
+        if (active !== current || current.webContents.isDestroyed()) {
+          throw new Error("Dimina simulator UI was replaced during invocation");
+        }
+        return await current.webContents.executeJavaScript(
+          activeExpression("invoke", [stableRegistration.id, method, params ?? null]),
+          true
+        );
+      }
+    };
+  }
+  function clear() {
+    for (const id of entries.keys()) uninstall(id);
+    entries.clear();
+    detach();
+  }
+  return { register, attach, detach, clear };
+}
+
 // src/main/services/projects/templates.ts
 function resolveTemplates(builtin, injected, mode) {
   let kept;
@@ -6253,6 +6422,8 @@ function createWorkbenchContext(opts) {
   ctx.registry.add(() => ctx.cdpSessionBroker.dispose());
   ctx.trustedWindowSenderIds = /* @__PURE__ */ new Map();
   ctx.simulatorApis = createSimulatorApiRegistry();
+  ctx.simulatorUiExtensions = createSimulatorUiExtensionRegistry();
+  ctx.registry.add(() => ctx.simulatorUiExtensions.clear());
   ctx.windows = createWindowService(opts.mainWindow);
   ctx.views = createViewManager(ctx);
   ctx.registry.add(() => ctx.views.disposeAll());
@@ -6919,7 +7090,7 @@ import { DisposableRegistry as DisposableRegistry5 } from "@dimina-kit/electron-
 // src/main/ipc/bridge-router.ts
 import { app as app12, ipcMain as ipcMain3, protocol as protocol2, session as electronSession, webContents as webContents3 } from "electron";
 import path17 from "node:path";
-import { pathToFileURL as pathToFileURL3 } from "node:url";
+import { pathToFileURL as pathToFileURL4 } from "node:url";
 
 // src/shared/request-core.ts
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
@@ -7073,7 +7244,7 @@ function setCorsHeaders(res) {
 // src/main/windows/service-host-window/create.ts
 import { app as app10, BrowserWindow as BrowserWindow5 } from "electron";
 import path16 from "node:path";
-import { pathToFileURL as pathToFileURL2 } from "node:url";
+import { pathToFileURL as pathToFileURL3 } from "node:url";
 var SERVICE_HOST_PARTITION = SHARED_MINIAPP_PARTITION;
 var serviceHostPreloadPath = path16.join(devtoolsPackageRoot, "dist/service-host/preload.cjs");
 var serviceHostHtmlPath = path16.join(devtoolsPackageRoot, "dist/service-host/service.html");
@@ -7096,7 +7267,7 @@ function constructServiceHostWindow(opts = {}) {
   });
 }
 function buildServiceHostSpawnUrl(opts) {
-  const url = new URL(pathToFileURL2(serviceHostHtmlPath).toString());
+  const url = new URL(pathToFileURL3(serviceHostHtmlPath).toString());
   url.searchParams.set("bridgeId", opts.bridgeId);
   url.searchParams.set("appId", opts.appId);
   url.searchParams.set("pagePath", opts.pagePath);
@@ -8297,8 +8468,8 @@ function installBridgeRouter(ctx) {
   const onNativeHostQuery = (event) => {
     const reply = {
       enabled: true,
-      renderHostHtmlUrl: pathToFileURL3(path17.join(devtoolsPackageRoot, "dist/render-host/pageFrame.html")).toString(),
-      renderPreloadUrl: pathToFileURL3(path17.join(devtoolsPackageRoot, "dist/render-host/preload.cjs")).toString(),
+      renderHostHtmlUrl: pathToFileURL4(path17.join(devtoolsPackageRoot, "dist/render-host/pageFrame.html")).toString(),
+      renderPreloadUrl: pathToFileURL4(path17.join(devtoolsPackageRoot, "dist/render-host/preload.cjs")).toString(),
       device: currentDevice ?? void 0
     };
     event.returnValue = reply;
@@ -9618,8 +9789,7 @@ function resolveRootPagePath(manifest, requestedPagePath) {
 function resolvePageWindowConfig(appConfig, pagePath) {
   const normalized = normalizePagePath(pagePath);
   const appWindow = appConfig.app?.window ?? {};
-  const pageEntry = appConfig.modules?.[normalized];
-  const pageWindow = pageEntry?.window ?? {};
+  const pageWindow = appConfig.modules?.[normalized] ?? {};
   return {
     navigationBarTitleText: pageWindow.navigationBarTitleText ?? appWindow.navigationBarTitleText ?? "",
     navigationBarBackgroundColor: pageWindow.navigationBarBackgroundColor ?? appWindow.navigationBarBackgroundColor ?? "#ffffff",
@@ -13169,6 +13339,14 @@ async function createDevtoolsRuntime(config = {}, 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(toDisposable8(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);

package/dist/main/ipc/bridge-router.js

@@ -2095,8 +2095,7 @@ function resolveRootPagePath(manifest, requestedPagePath) {
 function resolvePageWindowConfig(appConfig, pagePath) {
     const normalized = normalizePagePath(pagePath);
     const appWindow = appConfig.app?.window ?? {};
-    const pageEntry = appConfig.modules?.[normalized];
-    const pageWindow = pageEntry?.window ?? {};
+    const pageWindow = appConfig.modules?.[normalized] ?? {};
     return {
         navigationBarTitleText: pageWindow.navigationBarTitleText ?? appWindow.navigationBarTitleText ?? '',
         navigationBarBackgroundColor: pageWindow.navigationBarBackgroundColor ?? appWindow.navigationBarBackgroundColor ?? '#ffffff',

package/dist/main/services/simulator/ui-extensions.d.ts

@@ -0,0 +1,13 @@
+import type { WebContents } from 'electron';
+import type { SimulatorUiExtensionHandle, SimulatorUiExtensionRegistration } from '../../../shared/simulator-ui.js';
+export interface SimulatorUiExtensionRegistry {
+    register(registration: SimulatorUiExtensionRegistration): SimulatorUiExtensionHandle;
+    attach(webContents: WebContents): void;
+    detach(webContents?: WebContents): void;
+    clear(): void;
+}
+export interface SimulatorUiExtensionRegistryOptions {
+    loadSource?: (scriptPath: string) => Promise<string>;
+}
+export declare function createSimulatorUiExtensionRegistry(options?: SimulatorUiExtensionRegistryOptions): SimulatorUiExtensionRegistry;
+//# sourceMappingURL=ui-extensions.d.ts.map

package/dist/main/services/simulator/ui-extensions.js

@@ -0,0 +1,166 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+const EXTENSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+export function createSimulatorUiExtensionRegistry(options = {}) {
+    const loadSource = options.loadSource ?? (scriptPath => readFile(scriptPath, 'utf8'));
+    const entries = new Map();
+    let active = null;
+    function assertRegistration(registration) {
+        if (!EXTENSION_ID_RE.test(registration.id)) {
+            throw new Error(`Invalid simulator UI extension id: "${registration.id}"`);
+        }
+        if (!isAbsolute(registration.rendererScriptPath)) {
+            throw new Error('Simulator UI extension rendererScriptPath must be absolute');
+        }
+        if (entries.has(registration.id)) {
+            throw new Error(`Simulator UI extension "${registration.id}" is already registered`);
+        }
+    }
+    function activeExpression(method, args) {
+        return `globalThis.__diminaSimulatorUi.${method}(${args.map(arg => JSON.stringify(arg)).join(',')})`;
+    }
+    async function install(entry, target) {
+        const { id, rendererScriptPath } = entry.registration;
+        if (target.loaded.has(id))
+            return;
+        const pending = target.loading.get(id);
+        if (pending)
+            return await pending;
+        const generation = target.generation;
+        const task = (async () => {
+            // Read once per simulator document generation so downstream watch builds
+            // become visible after a hard reload without restarting the workbench.
+            const source = await loadSource(rendererScriptPath);
+            if (entries.get(id) !== entry
+                ||
+                    active !== target
+                || target.webContents.isDestroyed()
+                || !target.ready
+                || target.generation !== generation) {
+                throw new Error('Simulator UI extension target is no longer available');
+            }
+            const sourceUrl = pathToFileURL(rendererScriptPath).href;
+            const wrapped = `(()=>{\n${source}\n;return undefined\n})()\n//# sourceURL=${sourceUrl}`;
+            await target.webContents.executeJavaScript(wrapped, true);
+            if (entries.get(id) !== entry
+                ||
+                    active !== target
+                || target.webContents.isDestroyed()
+                || !target.ready
+                || target.generation !== generation) {
+                throw new Error('Simulator UI extension target was destroyed during installation');
+            }
+            const registered = await target.webContents.executeJavaScript(`Boolean(globalThis.__diminaSimulatorUi?.has(${JSON.stringify(id)}))`, true);
+            if (!registered) {
+                throw new Error(`Simulator UI extension "${id}" did not register its renderer implementation`);
+            }
+            target.loaded.add(id);
+        })().finally(() => {
+            if (target.loading.get(id) === task)
+                target.loading.delete(id);
+        });
+        target.loading.set(id, task);
+        return await task;
+    }
+    async function installAll(target) {
+        for (const entry of entries.values()) {
+            try {
+                await install(entry, target);
+            }
+            catch (error) {
+                console.warn(`[simulator-ui] failed to install "${entry.registration.id}":`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    function uninstall(id, target = active) {
+        if (!target)
+            return;
+        target.loaded.delete(id);
+        target.loading.delete(id);
+        if (!target.ready || target.webContents.isDestroyed())
+            return;
+        void target.webContents.executeJavaScript(`globalThis.__diminaSimulatorUi?.unregister(${JSON.stringify(id)})`, true).catch(() => { });
+    }
+    function detach(webContents) {
+        const target = active;
+        if (!target || (webContents && target.webContents !== webContents))
+            return;
+        active = null;
+        if (!target.webContents.isDestroyed()) {
+            target.webContents.removeListener('did-finish-load', target.onLoaded);
+        }
+        target.loaded.clear();
+        target.loading.clear();
+    }
+    function attach(webContents) {
+        detach();
+        const target = {
+            webContents,
+            ready: false,
+            generation: 0,
+            loaded: new Set(),
+            loading: new Map(),
+            onLoaded: () => { },
+        };
+        target.onLoaded = () => {
+            if (active !== target || webContents.isDestroyed())
+                return;
+            target.ready = true;
+            target.generation += 1;
+            target.loaded.clear();
+            target.loading.clear();
+            void installAll(target);
+        };
+        active = target;
+        webContents.on('did-finish-load', target.onLoaded);
+    }
+    function register(registration) {
+        assertRegistration(registration);
+        const stableRegistration = { ...registration };
+        const entry = {
+            registration: stableRegistration,
+        };
+        entries.set(stableRegistration.id, entry);
+        const target = active;
+        if (target?.ready) {
+            void install(entry, target).catch((error) => {
+                console.warn(`[simulator-ui] failed to install "${stableRegistration.id}":`, error instanceof Error ? error.message : String(error));
+            });
+        }
+        let disposed = false;
+        return {
+            dispose() {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (entries.get(stableRegistration.id) !== entry)
+                    return;
+                entries.delete(stableRegistration.id);
+                uninstall(stableRegistration.id);
+            },
+            async invoke(method, params) {
+                if (disposed || entries.get(stableRegistration.id) !== entry) {
+                    throw new Error(`Simulator UI extension "${stableRegistration.id}" is disposed`);
+                }
+                const current = active;
+                if (!current || current.webContents.isDestroyed() || !current.ready) {
+                    throw new Error('Dimina simulator UI is not ready');
+                }
+                await install(entry, current);
+                if (active !== current || current.webContents.isDestroyed()) {
+                    throw new Error('Dimina simulator UI was replaced during invocation');
+                }
+                return await current.webContents.executeJavaScript(activeExpression('invoke', [stableRegistration.id, method, params ?? null]), true);
+            },
+        };
+    }
+    function clear() {
+        for (const id of entries.keys())
+            uninstall(id);
+        entries.clear();
+        detach();
+    }
+    return { register, attach, detach, clear };
+}
+//# sourceMappingURL=ui-extensions.js.map

package/dist/main/services/views/native-simulator-view.js

@@ -70,6 +70,7 @@ export function createNativeSimulatorView(ctx, reconciler, deps) {
     function tearDownNativeSimulatorView(label) {
         if (!nativeSimulatorView)
             return;
+        ctx.simulatorUiExtensions?.detach(nativeSimulatorView.webContents);
         if (nativeSimulatorViewAdded && !ctx.windows.mainWindow.isDestroyed()) {
             try {
                 ctx.windows.mainWindow.contentView.removeChildView(nativeSimulatorView);
@@ -219,6 +220,8 @@ export function createNativeSimulatorView(ctx, reconciler, deps) {
         // and the renderer placeholder behind it are all the same color.
         view.setBackgroundColor(simDeskBg());
         const simWc = view.webContents;
+        // Keep downstream UI bundles bound to this WCV until shared teardown.
+        ctx.simulatorUiExtensions?.attach(simWc);
         // Keep the WCV surface in sync with the active color scheme. The
         // process-wide installThemeBackgroundSync() re-syncs BrowserWindows on a
         // theme switch, but this top-level WebContentsView is not a window, so its
@@ -248,6 +251,10 @@ export function createNativeSimulatorView(ctx, reconciler, deps) {
         // URL in will-attach (where `params.src` carries the full URL) and consumed
         // FIFO in the matching did-attach — `guestWc.getURL()` is still empty there.
         // Per-attach scope: a fresh simWc + handlers are built on every (re)attach.
+        // (The guest's `bgColor` query param — WeChat/Android/Harmony white-flash
+        // parity — is consumed entirely outside main: device-shell.tsx's `<webview>`
+        // CSS background and render-host/preload.cjs both read it directly, since
+        // `WebContents` has no `setBackgroundColor` for main to call here.)
         const pendingGuestIsTab = [];
         simWc.on('will-attach-webview', (_event, webPreferences, params) => {
             ;

package/dist/main/services/views/view-manager.d.ts

@@ -64,6 +64,11 @@ export interface ViewManagerContext {
      * Optional so partial test contexts compile.
      */
     simulatorApis?: WorkbenchContext['simulatorApis'];
+    /**
+     * Host-registered UI extensions that follow the native simulator WCV.
+     * Optional only for focused view-manager test doubles.
+     */
+    simulatorUiExtensions?: WorkbenchContext['simulatorUiExtensions'];
 }
 /**
  * Unified lifecycle manager for Electron WebContentsView overlays.

package/dist/main/services/workbench-context.d.ts

@@ -18,6 +18,7 @@ import { type ViewManager } from './views/view-manager.js';
 import { type WindowService } from './window-service.js';
 import { type WorkspaceService } from './workspace/workspace-service.js';
 import { type SimulatorApiRegistry } from './simulator/custom-apis.js';
+import { type SimulatorUiExtensionRegistry } from './simulator/ui-extensions.js';
 import { sanitizeTemplates } from './projects/templates.js';
 import type { ProjectsProvider, ProjectTemplate } from './projects/types.js';
 import type { CustomCreateProjectDialogResult } from '../../shared/types.js';
@@ -123,6 +124,11 @@ export interface WorkbenchContext {
      * One registry per context — no process-global crosstalk.
      */
     simulatorApis: SimulatorApiRegistry;
+    /**
+     * Per-context downstream simulator UI extensions. It owns renderer bundle
+     * installation and follows the active native simulator WebContentsView.
+     */
+    simulatorUiExtensions: SimulatorUiExtensionRegistry;
     /** Aggregates dispose handlers for every IPC handler, listener, watcher, and CDP session registered by the workbench. */
     registry: DisposableRegistry;
     /**

package/dist/main/services/workbench-context.js

@@ -12,6 +12,7 @@ import { openSettingsWindow } from '../windows/settings-window/index.js';
 import { createWorkspaceService, } from './workspace/workspace-service.js';
 import { createLocalProjectsProvider } from './projects/local-provider.js';
 import { createSimulatorApiRegistry, } from './simulator/custom-apis.js';
+import { createSimulatorUiExtensionRegistry, } from './simulator/ui-extensions.js';
 import { resolveTemplates, sanitizeTemplates } from './projects/templates.js';
 import { BUILTIN_TEMPLATES } from './projects/builtin-templates.js';
 export function createWorkbenchContext(opts) {
@@ -34,6 +35,8 @@ export function createWorkbenchContext(opts) {
     ctx.registry.add(() => ctx.cdpSessionBroker.dispose());
     ctx.trustedWindowSenderIds = new Map();
     ctx.simulatorApis = createSimulatorApiRegistry();
+    ctx.simulatorUiExtensions = createSimulatorUiExtensionRegistry();
+    ctx.registry.add(() => ctx.simulatorUiExtensions.clear());
     ctx.windows = createWindowService(opts.mainWindow);
     ctx.views = createViewManager(ctx);
     // Full view teardown belongs to the CONTEXT's life, not a project's: