@dimina-kit/devtools 0.4.0-dev.20260612025610 → 0.4.0-dev.20260615070430

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)）。
 
@@ -42,6 +42,12 @@ launch({
   rendererDir,
   apiNamespaces: ['my'],
   brandingProvider: () => ({ appName: '我的开发工具' }),
+  headerAvatarProvider: () => {
+    const user = getCurrentUser()
+    return user
+      ? { displayName: user.name, displayInitial: user.name, avatarUrl: user.avatarUrl }
+      : null
+  },
   icon: '/path/to/icon.png',
   menuBuilder: (mainWindow, menuCtx) => {
     // menuCtx 是 MenuContext（只读 menu 相关状态）
@@ -147,7 +153,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,10 +183,14 @@ 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                  |
+| `headerAvatarProvider` | `() => HeaderAvatarInfo \| null \| Promise<HeaderAvatarInfo \| null>` | — | 内置 header 头像 slot 的宿主数据源；返回 `null` / `undefined` 时隐藏 |
+| `headerAvatarActionHandler` | `() => void \| Promise<void>` | — | 内置 header 头像 slot 的点击处理；未提供时点击无业务副作用 |
+| `headerActionsProvider` | `() => HeaderActionInfo[] \| null \| Promise<HeaderActionInfo[] \| null>` | — | 内置 header 三栏里的少量宿主命令按钮 |
+| `headerActionHandler` | `(id: string) => void \| Promise<void>` | — | 处理 `headerActionsProvider` 返回按钮的点击 |
 | `headerHeight`     | `number`             | —                   | **已废弃，运行时忽略**：头部栏恒为 40px（`HEADER_H`）；需要自定义工具栏请用 host toolbar WCV |
 
 ### WorkbenchAppConfig（扩展 WorkbenchConfig）
@@ -208,6 +218,78 @@ src/
 | `instance.registerSimulatorApi(name, handler)` | 注册 simulator 自定义 API，小程序里 `wx.<name>()` 调用（详见下方"Simulator 自定义 API"）。返回 `Disposable` |
 | `instance.ipc` | `IpcRegistry` 实例，`instance.ipc.handle(channel, fn)` 注册自定义 IPC；已绑定 `senderPolicy` 网关 |
 | `instance.registerTrustedWindow(win)` | 把 host 自有弹窗 `BrowserWindow` 加入受信 sender 集，否则其发起的 `instance.ipc` 调用会被网关拒绝。窗口关闭即移除 |
+| `instance.refreshHeaderAvatar()` | 通知 main renderer 重新调用 `headerAvatarProvider`，用于宿主登录态 / 头像变更后刷新内置 header 头像 |
+| `instance.refreshHeaderActions()` | 通知 main renderer 重新调用 `headerActionsProvider`，用于宿主 action 文案 / disabled 状态变化后刷新 |
+
+### Header Avatar
+
+`headerAvatarProvider` 是内置 project header 头像 slot 的唯一数据源。devtools 会通过 `app:getHeaderAvatar` 拉取一个可序列化 DTO 并在固定 header toolbar 内渲染；宿主不需要、也不应该依赖 renderer 内部组件。
+
+该 slot 只承载当前账号 / 身份入口，不是通用业务按钮扩展点。少量必须贴合内置 header 三栏布局的命令按钮使用下方的 `headerActionsProvider`；完整自定义工具栏、复杂状态展示、表单/筛选器、可变高度内容仍应使用 host toolbar WCV（`instance.context.views.hostToolbar.loadURL/loadFile` + `send/onMessage`），由宿主拥有内容、样式和高度。
+
+```typescript
+launch({
+  headerAvatarProvider: () => {
+    const user = qdmpSession.currentUser()
+    return user
+      ? {
+          displayName: user.nickname,
+          displayInitial: user.nickname,
+          avatarUrl: user.avatarUrl,
+          tooltip: user.nickname,
+        }
+      : null
+  },
+  onSetup(instance) {
+    qdmpSession.onUserChanged(() => instance.refreshHeaderAvatar())
+  },
+})
+```
+
+`HeaderAvatarInfo` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `displayName` | 用户名；用于 tooltip / aria 文本和 fallback 首字 |
+| `displayInitial` | 可选 fallback 文本；头像图片缺失或加载失败时取首字显示 |
+| `avatarUrl` | 头像图片 URL 或 data URL |
+| `tooltip` | 可选 tooltip 覆盖；默认用 `displayName` |
+
+### Header Actions
+
+`headerActionsProvider` 用于把少量宿主命令渲染到内置 project header 的三栏中。它不是 host toolbar WCV 的替代品：只适合 1-4 个短文本命令，且按钮高度固定、宽度受 header 约束。
+
+placement 对应内置 header 的三个区域：
+
+| placement | 渲染位置 |
+| --- | --- |
+| `left` | 左区最右侧，位于头像 / 面板显隐 controls 之后 |
+| `center` | 中区最右侧，位于编译模式 / 重新编译 / 编译状态之后 |
+| `right` | 右区最左侧，位于布局 controls / 设置按钮之前 |
+
+```typescript
+launch({
+  headerActionsProvider: () => [
+    { id: 'open', label: '打开', placement: 'left' },
+    { id: 'bindApp', label: '绑定应用', placement: 'left' },
+    { id: 'preview', label: '真机预览', placement: 'center' },
+    { id: 'upload', label: '上传', placement: 'right' },
+  ],
+  headerActionHandler: async (id) => {
+    await commands.run(id)
+  },
+})
+```
+
+`HeaderActionInfo` 字段：
+
+| 字段 | 说明 |
+| --- | --- |
+| `id` | 稳定 action id；点击时传给 `headerActionHandler` |
+| `label` | 短按钮文案 |
+| `tooltip` | 可选 tooltip 覆盖；默认用 `label` |
+| `placement` | `left` / `center` / `right`；默认 `right` |
+| `disabled` | 可选禁用态 |
 
 ### 内置面板 ID
 
@@ -483,7 +565,7 @@ launch({
 
 ## Host Toolbar（宿主自定义工具栏）
 
-下游通过 `instance.context.views.hostToolbar` 拥有 devtools 头部下方的工具栏条（一个 WebContentsView）：`loadURL` / `loadFile` 加载自己的内容，`setPreloadPath` 注入自己的 preload，`setHeightMode` 钉死或自动跟随内容高度（自动模式要求内容自带 shrink-to-fit 的 `[data-host-toolbar-root]` 包裹元素；`{ fixed }` 校验入参——非有限数或负数同步抛 `TypeError` 且不污染既有模式）。
+下游通过 `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
 

package/dist/main/api.d.ts

@@ -16,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, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
+export type { WorkbenchConfig, WorkbenchAppConfig, CompilationAdapter, ProjectSession, HeaderAvatarInfo, HeaderAvatarProvider, HeaderActionInfo, HeaderActionPlacement, HeaderActionsProvider, BuiltinPanelId, BuiltinModuleId, UpdateChecker, UpdateInfo, } from '../shared/types.js';
 //# sourceMappingURL=api.d.ts.map

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

@@ -15,6 +15,10 @@ export interface WorkbenchAppInstance {
     registerTrustedWindow: (win: BrowserWindow) => Disposable;
     /** Registers a simulator custom API into this context's registry. */
     registerSimulatorApi: (name: string, handler: SimulatorApiHandler) => Disposable;
+    /** Ask the main renderer to re-read the header avatar provider. */
+    refreshHeaderAvatar: () => void;
+    /** Ask the main renderer to re-read the header actions provider. */
+    refreshHeaderActions: () => void;
     automationServer?: AutomationServer;
     updateManager?: UpdateManager;
     dispose: () => Promise<void>;

package/dist/main/app/app.js

@@ -149,6 +149,10 @@ function createContext(config, mainWindow, rendererDir) {
         appName: config.appName,
         apiNamespaces: config.apiNamespaces,
         brandingProvider: config.brandingProvider,
+        headerAvatarProvider: config.headerAvatarProvider,
+        headerAvatarActionHandler: config.headerAvatarActionHandler,
+        headerActionsProvider: config.headerActionsProvider,
+        headerActionHandler: config.headerActionHandler,
         // The host-supplied ProjectsProvider / template types in `shared/types`
         // are structurally compatible with the main-process equivalents —
         // these casts are safe; we re-narrow at the workspace-service /
@@ -352,6 +356,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))),
+        refreshHeaderAvatar: () => context.notify.headerAvatarChanged(),
+        refreshHeaderActions: () => context.notify.headerActionsChanged(),
         dispose: () => disposeContext(context),
     };
     if (config.onSetup) {

package/dist/main/index.bundle.js

@@ -374,6 +374,10 @@ var ProjectChannel = {
   GetCompileConfig: "project:getCompileConfig",
   SaveCompileConfig: "project:saveCompileConfig",
   Status: "project:status",
+  // Main → renderer push of per-line dmcc compile logs (devkit `onLog`).
+  // Dedicated channel: `project:status` keeps its one-event-per-payload
+  // contract (compileEvents), this one carries the line stream (compileLogs).
+  CompileLog: "project:compileLog",
   CaptureThumbnail: "project:captureThumbnail",
   GetThumbnail: "project:getThumbnail"
 };
@@ -440,7 +444,17 @@ var ViewChannel = {
    * main → main-window renderer: push the reserved host-toolbar height so the
    * renderer placeholder div resizes (closing the dynamic-height loop).
    */
-  HostToolbarHeightChanged: "view:host-toolbar:height-changed"
+  HostToolbarHeightChanged: "view:host-toolbar:height-changed",
+  /**
+   * main ← main-window renderer (invoke): pull the last NOTIFIED toolbar
+   * height retained in main. Mount-time replay companion to
+   * `HostToolbarHeightChanged`: the push listener mounts with the project
+   * view and the toolbar's size-advertiser deduplicates (never re-reports),
+   * so a height pushed while no project view was mounted would otherwise be
+   * lost forever (cold start on the project list races it; close-project →
+   * reopen hits it deterministically). No payload; resolves a number.
+   */
+  HostToolbarGetHeight: "view:host-toolbar:get-height"
 };
 var PopoverChannel = {
   Show: "popover:show",
@@ -453,7 +467,13 @@ var WindowChannel = {
   NavigateBack: "window:navigateBack"
 };
 var AppChannel = {
-  GetBranding: "app:getBranding"
+  GetBranding: "app:getBranding",
+  GetHeaderAvatar: "app:getHeaderAvatar",
+  InvokeHeaderAvatar: "app:invokeHeaderAvatar",
+  HeaderAvatarChanged: "app:headerAvatarChanged",
+  GetHeaderActions: "app:getHeaderActions",
+  InvokeHeaderAction: "app:invokeHeaderAction",
+  HeaderActionsChanged: "app:headerActionsChanged"
 };
 var AutomationChannel = {
   GetPort: "automation:port"
@@ -966,6 +986,9 @@ function createRendererNotifier(ctx) {
     projectStatus(payload) {
       sendToMain(ProjectChannel.Status, payload);
     },
+    compileLog(payload) {
+      sendToMain(ProjectChannel.CompileLog, payload);
+    },
     windowNavigateBack() {
       sendToMain(WindowChannel.NavigateBack);
     },
@@ -978,6 +1001,12 @@ function createRendererNotifier(ctx) {
     hostToolbarHeightChanged(height) {
       sendToMain(ViewChannel.HostToolbarHeightChanged, height);
     },
+    headerAvatarChanged() {
+      sendToMain(AppChannel.HeaderAvatarChanged);
+    },
+    headerActionsChanged() {
+      sendToMain(AppChannel.HeaderActionsChanged);
+    },
     editorOpenFile(payload) {
       sendToMain(EditorChannel.OpenFile, payload);
     },
@@ -1841,6 +1870,7 @@ function createViewManager(ctx) {
   let hostToolbarViewAdded = false;
   let hostToolbarRuntimeAcquired = false;
   let hostToolbarHeightMode = "auto";
+  let hostToolbarLastHeight = 0;
   const hostToolbarPort = createHostToolbarPortChannel({
     isCurrent: (wc) => liveHostToolbarWebContents() === wc
   });
@@ -1943,9 +1973,13 @@ function createViewManager(ctx) {
     }
     view.setBounds(bounds);
   }
+  function notifyHostToolbarHeight(height) {
+    hostToolbarLastHeight = height;
+    ctx.notify.hostToolbarHeightChanged(height);
+  }
   function setHostToolbarHeight(extent) {
     if (hostToolbarHeightMode !== "auto") return;
-    ctx.notify.hostToolbarHeightChanged(extent);
+    notifyHostToolbarHeight(extent);
   }
   function hideHostToolbar() {
     if (hostToolbarView && hostToolbarViewAdded && !ctx.windows.mainWindow.isDestroyed()) {
@@ -1955,7 +1989,7 @@ function createViewManager(ctx) {
       }
     }
     hostToolbarViewAdded = false;
-    ctx.notify.hostToolbarHeightChanged(0);
+    notifyHostToolbarHeight(0);
   }
   const hostToolbar = {
     async loadURL(url) {
@@ -1985,7 +2019,7 @@ function createViewManager(ctx) {
       }
       hostToolbarHeightMode = mode;
       if (mode !== "auto") {
-        ctx.notify.hostToolbarHeightChanged(mode.fixed);
+        notifyHostToolbarHeight(mode.fixed);
       }
     },
     onMessage(channel, handler) {
@@ -2546,6 +2580,7 @@ function createViewManager(ctx) {
       return popoverView.webContents.id;
     },
     getHostToolbarWebContentsId: () => liveHostToolbarWebContents()?.id ?? null,
+    getHostToolbarHeight: () => hostToolbarLastHeight,
     setNativeSimulatorViewBounds,
     resize,
     setSimulatorDevtoolsBounds,
@@ -2823,6 +2858,7 @@ function createWorkspaceService(ctx) {
   let currentSession = null;
   let currentProjectPath = "";
   let lastClosedProjectPath = "";
+  let logGeneration = 0;
   function sendStatus(status2, message, hotReload) {
     ctx.notify.projectStatus(hotReload ? { status: status2, message, hotReload: true } : { status: status2, message });
   }
@@ -2871,6 +2907,7 @@ function createWorkspaceService(ctx) {
     validateProjectDir: async (dirPath) => provider.validateProjectDir ? provider.validateProjectDir(dirPath) : null,
     async openProject(projectPath) {
       clearSimulatorServicewechatReferer();
+      logGeneration++;
       await disposeSession();
       currentProjectPath = "";
       lastClosedProjectPath = "";
@@ -2881,6 +2918,7 @@ function createWorkspaceService(ctx) {
       }
       sendStatus("compiling", "\u6B63\u5728\u7F16\u8BD1...");
       const { compile } = loadWorkbenchSettings();
+      const sessionGeneration = ++logGeneration;
       let session5;
       try {
         session5 = await ctx.adapter.openProject({
@@ -2888,7 +2926,21 @@ function createWorkspaceService(ctx) {
           sourcemap: true,
           watch: compile.watch,
           onRebuild: () => sendStatus("ready", "\u7F16\u8BD1\u5B8C\u6210\uFF0C\u5DF2\u70ED\u66F4\u65B0", true),
-          onBuildError: (err) => sendStatus("error", String(err))
+          onBuildError: (err) => sendStatus("error", String(err)),
+          // Per-line dmcc log (already filtered in devkit). Stamp the
+          // wall-clock capture time here and push verbatim on the dedicated
+          // compile-log channel — never through projectStatus, whose
+          // one-event-per-payload contract feeds compileEvents. Stale lines
+          // (a closed/replaced session's worker flushing its buffers) are
+          // dropped via the generation check.
+          onLog: (entry) => {
+            if (sessionGeneration !== logGeneration) return;
+            ctx.notify.compileLog({
+              stream: entry.stream,
+              text: entry.text,
+              at: Date.now()
+            });
+          }
         });
       } catch (err) {
         clearSimulatorServicewechatReferer();
@@ -2922,6 +2974,7 @@ function createWorkspaceService(ctx) {
       };
     },
     async closeProject() {
+      logGeneration++;
       clearSimulatorServicewechatReferer();
       await disposeSession();
       if (currentProjectPath !== "") lastClosedProjectPath = currentProjectPath;
@@ -3066,7 +3119,11 @@ function createWorkbenchContext(opts) {
     rendererDir: opts.rendererDir,
     apiNamespaces: opts.apiNamespaces ?? [],
     appName: opts.appName ?? "Dimina DevTools",
-    brandingProvider: opts.brandingProvider
+    brandingProvider: opts.brandingProvider,
+    headerAvatarProvider: opts.headerAvatarProvider,
+    headerAvatarActionHandler: opts.headerAvatarActionHandler,
+    headerActionsProvider: opts.headerActionsProvider,
+    headerActionHandler: opts.headerActionHandler
   };
   ctx.registry = new DisposableRegistry3();
   ctx.connections = createConnectionRegistry();
@@ -3166,10 +3223,70 @@ function installAppMenu(ctx) {
 }
 
 // src/main/ipc/app.ts
+function readString(value) {
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+function normalizeHeaderAvatar(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const avatar = {};
+  const displayName = readString(raw.displayName);
+  const displayInitial = readString(raw.displayInitial);
+  const avatarUrl = readString(raw.avatarUrl);
+  const tooltip = readString(raw.tooltip);
+  if (displayName) avatar.displayName = displayName;
+  if (displayInitial) avatar.displayInitial = displayInitial;
+  if (avatarUrl) avatar.avatarUrl = avatarUrl;
+  if (tooltip) avatar.tooltip = tooltip;
+  return avatar.displayName || avatar.displayInitial || avatar.avatarUrl ? avatar : null;
+}
+function readPlacement(value) {
+  return value === "left" || value === "center" || value === "right" ? value : void 0;
+}
+function normalizeHeaderAction(value) {
+  if (!value || typeof value !== "object") return null;
+  const raw = value;
+  const id = readString(raw.id);
+  const label = readString(raw.label);
+  if (!id || !label) return null;
+  const action = { id, label };
+  const tooltip = readString(raw.tooltip);
+  const placement = readPlacement(raw.placement);
+  if (tooltip) action.tooltip = tooltip;
+  if (placement) action.placement = placement;
+  if (typeof raw.disabled === "boolean") action.disabled = raw.disabled;
+  return action;
+}
+function normalizeHeaderActions(value) {
+  if (!Array.isArray(value)) return [];
+  const actions = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const item of value) {
+    const action = normalizeHeaderAction(item);
+    if (!action || seen.has(action.id)) continue;
+    seen.add(action.id);
+    actions.push(action);
+  }
+  return actions.slice(0, 8);
+}
 function registerAppIpc(ctx) {
   return new IpcRegistry(ctx.senderPolicy).handle(AppChannel.GetBranding, async () => {
     if (ctx.brandingProvider) return ctx.brandingProvider();
     return { appName: ctx.appName };
+  }).handle(AppChannel.GetHeaderAvatar, async () => {
+    if (!ctx.headerAvatarProvider) return null;
+    return normalizeHeaderAvatar(await ctx.headerAvatarProvider());
+  }).handle(AppChannel.InvokeHeaderAvatar, async () => {
+    await ctx.headerAvatarActionHandler?.();
+  }).handle(AppChannel.GetHeaderActions, async () => {
+    if (!ctx.headerActionsProvider) return [];
+    return normalizeHeaderActions(await ctx.headerActionsProvider());
+  }).handle(AppChannel.InvokeHeaderAction, async (_event, id) => {
+    const actionId = readString(id);
+    if (!actionId) return;
+    await ctx.headerActionHandler?.(actionId);
   });
 }
 
@@ -4756,12 +4873,16 @@ function summarizeBridgeMsg(payload) {
 var API_CALL_TIMEOUT_MS = 5e3;
 function resolveCurrentApp(state, ctx, appId) {
   if (appId) {
-    for (const ap of state.appSessions.values()) if (ap.appId === appId) return ap;
+    let match;
+    for (const ap of state.appSessions.values()) if (ap.appId === appId) match = ap;
+    if (match) return match;
   }
   const appInfo = ctx.workspace?.getSession?.()?.appInfo;
   const activeAppId = appInfo?.appId;
   if (activeAppId) {
-    for (const ap of state.appSessions.values()) if (ap.appId === activeAppId) return ap;
+    let match;
+    for (const ap of state.appSessions.values()) if (ap.appId === activeAppId) match = ap;
+    if (match) return match;
   }
   let last;
   for (const ap of state.appSessions.values()) last = ap;
@@ -4778,7 +4899,11 @@ function installBridgeRouter(ctx) {
     emitRenderEvent: () => {
     },
     connections: ctx.connections,
-    debugTap: createDebugTap({ enabled: resolveDebugTapEnabled() })
+    debugTap: createDebugTap({ enabled: resolveDebugTapEnabled() }),
+    evictAppDataBridges: (ap) => {
+      if (!ctx.appData) return;
+      for (const page of ap.pages.values()) ctx.appData.evictBridge(ap.appId, page.bridgeId);
+    }
   };
   const prewarmPoolSize = resolvePrewarmPoolSize();
   if (prewarmPoolSize > 0) {
@@ -4950,9 +5075,6 @@ function installBridgeRouter(ctx) {
       console.warn(`[bridge-router] DISPOSE rejected: sender belongs to ${senderApp.appSessionId}, target ${target.appSessionId}`);
       return;
     }
-    if (ctx.appData) {
-      for (const page of target.pages.values()) ctx.appData.evictBridge(target.appId, page.bridgeId);
-    }
     void disposeAppSession(state, target.appSessionId);
   };
   ipcMain3.on(BRIDGE_CHANNELS.DISPOSE, onDispose);
@@ -5135,6 +5257,10 @@ async function handleSpawn(state, ctx, event, opts) {
   };
   appSession.onServiceClosed = onServiceClosed;
   serviceWindow.once("closed", onServiceClosed);
+  const onSimulatorDestroyed = () => {
+    void disposeAppSession(state, appSessionId);
+  };
+  simulatorWc.once("destroyed", onSimulatorDestroyed);
   if (usedPool) {
     const bootOnServiceLoad = () => {
       if (serviceWindow.isDestroyed()) return;
@@ -5639,6 +5765,7 @@ async function disposeAppSession(state, appSessionId, opts = {}) {
   const ap = state.appSessions.get(appSessionId);
   if (!ap) return;
   state.appSessions.delete(appSessionId);
+  state.evictAppDataBridges(ap);
   for (const [requestId, pending] of state.pendingApiCalls) {
     if (pending.appSessionId !== appSessionId) continue;
     clearTimeout(pending.timer);
@@ -5804,7 +5931,7 @@ function registerViewsIpc(ctx) {
       args
     );
     ctx.views.setHostToolbarBounds(bounds);
-  });
+  }).handle(ViewChannel.HostToolbarGetHeight, () => ctx.views.getHostToolbarHeight());
   const onAdvertiseHeight = (event, ...args) => {
     if (event.sender.id !== ctx.views.getHostToolbarWebContentsId()) return;
     let extent;
@@ -8768,6 +8895,10 @@ function createContext(config, mainWindow, rendererDir2) {
     appName: config.appName,
     apiNamespaces: config.apiNamespaces,
     brandingProvider: config.brandingProvider,
+    headerAvatarProvider: config.headerAvatarProvider,
+    headerAvatarActionHandler: config.headerAvatarActionHandler,
+    headerActionsProvider: config.headerActionsProvider,
+    headerActionHandler: config.headerActionHandler,
     // The host-supplied ProjectsProvider / template types in `shared/types`
     // are structurally compatible with the main-process equivalents —
     // these casts are safe; we re-narrow at the workspace-service /
@@ -8904,6 +9035,8 @@ 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(toDisposable8(context.simulatorApis.register(name, handler))),
+    refreshHeaderAvatar: () => context.notify.headerAvatarChanged(),
+    refreshHeaderActions: () => context.notify.headerActionsChanged(),
     dispose: () => disposeContext(context)
   };
   if (config.onSetup) {

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

@@ -1,4 +1,6 @@
 import type { WorkbenchContext } from '../services/workbench-context.js';
 import type { Disposable } from '@dimina-kit/electron-deck/main';
-export declare function registerAppIpc(ctx: Pick<WorkbenchContext, 'brandingProvider' | 'appName' | 'senderPolicy'>): Disposable;
+type AppIpcContext = Pick<WorkbenchContext, 'brandingProvider' | 'appName' | 'headerAvatarProvider' | 'headerAvatarActionHandler' | 'headerActionsProvider' | 'headerActionHandler' | 'senderPolicy'>;
+export declare function registerAppIpc(ctx: AppIpcContext): Disposable;
+export {};
 //# sourceMappingURL=app.d.ts.map

package/dist/main/ipc/app.js

@@ -1,11 +1,91 @@
 import { AppChannel } from '../../shared/ipc-channels.js';
 import { IpcRegistry } from '../utils/ipc-registry.js';
+function readString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function normalizeHeaderAvatar(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const avatar = {};
+    const displayName = readString(raw.displayName);
+    const displayInitial = readString(raw.displayInitial);
+    const avatarUrl = readString(raw.avatarUrl);
+    const tooltip = readString(raw.tooltip);
+    if (displayName)
+        avatar.displayName = displayName;
+    if (displayInitial)
+        avatar.displayInitial = displayInitial;
+    if (avatarUrl)
+        avatar.avatarUrl = avatarUrl;
+    if (tooltip)
+        avatar.tooltip = tooltip;
+    return avatar.displayName || avatar.displayInitial || avatar.avatarUrl ? avatar : null;
+}
+function readPlacement(value) {
+    return value === 'left' || value === 'center' || value === 'right' ? value : undefined;
+}
+function normalizeHeaderAction(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const raw = value;
+    const id = readString(raw.id);
+    const label = readString(raw.label);
+    if (!id || !label)
+        return null;
+    const action = { id, label };
+    const tooltip = readString(raw.tooltip);
+    const placement = readPlacement(raw.placement);
+    if (tooltip)
+        action.tooltip = tooltip;
+    if (placement)
+        action.placement = placement;
+    if (typeof raw.disabled === 'boolean')
+        action.disabled = raw.disabled;
+    return action;
+}
+function normalizeHeaderActions(value) {
+    if (!Array.isArray(value))
+        return [];
+    const actions = [];
+    const seen = new Set();
+    for (const item of value) {
+        const action = normalizeHeaderAction(item);
+        if (!action || seen.has(action.id))
+            continue;
+        seen.add(action.id);
+        actions.push(action);
+    }
+    return actions.slice(0, 8);
+}
 export function registerAppIpc(ctx) {
     return new IpcRegistry(ctx.senderPolicy)
         .handle(AppChannel.GetBranding, async () => {
         if (ctx.brandingProvider)
             return ctx.brandingProvider();
         return { appName: ctx.appName };
+    })
+        .handle(AppChannel.GetHeaderAvatar, async () => {
+        if (!ctx.headerAvatarProvider)
+            return null;
+        return normalizeHeaderAvatar(await ctx.headerAvatarProvider());
+    })
+        .handle(AppChannel.InvokeHeaderAvatar, async () => {
+        await ctx.headerAvatarActionHandler?.();
+    })
+        .handle(AppChannel.GetHeaderActions, async () => {
+        if (!ctx.headerActionsProvider)
+            return [];
+        return normalizeHeaderActions(await ctx.headerActionsProvider());
+    })
+        .handle(AppChannel.InvokeHeaderAction, async (_event, id) => {
+        const actionId = readString(id);
+        if (!actionId)
+            return;
+        await ctx.headerActionHandler?.(actionId);
     });
 }
 //# sourceMappingURL=app.js.map