@dimina-kit/devtools 0.4.0-dev.20260616102751 → 0.4.0-dev.20260618090552

package/dist/main/services/layout/index.d.ts

@@ -26,7 +26,19 @@ export declare function computeNativeSimulatorViewParams(rect: {
     bounds: Bounds;
     zoomFactor: number;
 };
+/** Renderer-side width of the settings PANEL (the opaque right strip). The
+ * settings WebContentsView itself spans the full content area (see
+ * `computeSettingsBounds`) as a transparent backdrop; the panel is positioned
+ * inside it at this width by `settings.tsx`. */
 export declare const SETTINGS_W = 320;
+/**
+ * The settings overlay is a FULL-content-area transparent backdrop (header
+ * excluded), identical to the popover region — NOT a right-edge strip. The
+ * renderer paints a transparent backdrop over the whole area and an opaque
+ * `SETTINGS_W`-wide panel on the right; a click on the transparent backdrop
+ * closes the overlay (clicks outside the panel must reach the backdrop, which is
+ * only possible when the view spans the whole area rather than just the strip).
+ */
 export declare function computeSettingsBounds(contentWidth: number, contentHeight: number, headerHeight: number): Bounds;
 export declare function computePopoverBounds(contentWidth: number, contentHeight: number, headerHeight: number): Bounds;
 //# sourceMappingURL=index.d.ts.map

package/dist/main/services/layout/index.js

@@ -23,12 +23,24 @@ export function computeNativeSimulatorViewParams(rect, zoomPercent) {
         zoomFactor,
     };
 }
+/** Renderer-side width of the settings PANEL (the opaque right strip). The
+ * settings WebContentsView itself spans the full content area (see
+ * `computeSettingsBounds`) as a transparent backdrop; the panel is positioned
+ * inside it at this width by `settings.tsx`. */
 export const SETTINGS_W = 320;
+/**
+ * The settings overlay is a FULL-content-area transparent backdrop (header
+ * excluded), identical to the popover region — NOT a right-edge strip. The
+ * renderer paints a transparent backdrop over the whole area and an opaque
+ * `SETTINGS_W`-wide panel on the right; a click on the transparent backdrop
+ * closes the overlay (clicks outside the panel must reach the backdrop, which is
+ * only possible when the view spans the whole area rather than just the strip).
+ */
 export function computeSettingsBounds(contentWidth, contentHeight, headerHeight) {
     return {
-        x: Math.max(0, contentWidth - SETTINGS_W),
+        x: 0,
         y: headerHeight,
-        width: Math.min(SETTINGS_W, Math.max(1, contentWidth)),
+        width: Math.max(1, contentWidth),
         height: Math.max(1, contentHeight - headerHeight),
     };
 }

package/dist/main/services/projects/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Public extensibility surface for the project list panel. Hosts that embed
- * dimina-devtools (e.g. qdmp) can inject implementations of these types via
+ * dimina-devtools (downstream hosts) can inject implementations of these types via
  * `WorkbenchAppConfig` to fully take over the project source-of-truth, the
  * template catalog, and the "新建项目" dialog.
  */

package/dist/main/services/projects/types.js

@@ -1,6 +1,6 @@
 /**
  * Public extensibility surface for the project list panel. Hosts that embed
- * dimina-devtools (e.g. qdmp) can inject implementations of these types via
+ * dimina-devtools (downstream hosts) can inject implementations of these types via
  * `WorkbenchAppConfig` to fully take over the project source-of-truth, the
  * template catalog, and the "新建项目" dialog.
  */

package/dist/main/services/service-console/console-api.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Pure helpers for the native-host service-console forwarder.
+ *
+ * Under native-host the service-host's console used to be captured by a
+ * `console.*` monkeypatch in `service-host/preload.cjs`. That wrapper added a
+ * stack frame, so Chrome DevTools (attached natively to the service host)
+ * attributed EVERY service-layer log to the wrapper line (`preload.cjs:237`)
+ * instead of the developer's source. We now capture via CDP
+ * `Runtime.consoleAPICalled` instead, which preserves native source attribution.
+ *
+ * These functions turn the CDP event shape into the `GuestConsoleEntry` shape
+ * the existing console fan-out (automation `App.logAdded`) expects, WITHOUT any
+ * electron / IO dependency so they are unit-testable in isolation. The async
+ * deep-fetch (`Runtime.callFunctionOn`) for object args lives in `index.ts`.
+ */
+/**
+ * sourceURL stamped on the render→service `[视图]` re-injection script
+ * (`console-forward.buildForwardScript`). The CDP capture skips any
+ * `consoleAPICalled` whose top frame carries this URL so a forwarded render line
+ * is not re-captured and re-broadcast as a service entry (duplicate / loop).
+ */
+export declare const RENDER_FORWARD_SOURCE_URL = "dimina://render-console-forward";
+export type ConsoleLevel = 'log' | 'warn' | 'error' | 'info' | 'debug';
+/** Subset of a CDP `Runtime.RemoteObject` we read. */
+export interface RemoteObjectLike {
+    type?: string;
+    subtype?: string;
+    value?: unknown;
+    unserializableValue?: string;
+    description?: string;
+    objectId?: string;
+    preview?: {
+        properties?: Array<{
+            name: string;
+            value: string;
+            type: string;
+        }>;
+        subtype?: string;
+        overflow?: boolean;
+    };
+}
+/** Subset of a CDP `Runtime.consoleAPICalled` params we read. */
+export interface ConsoleApiParamsLike {
+    type?: string;
+    args?: RemoteObjectLike[];
+    stackTrace?: {
+        callFrames?: Array<{
+            url?: string;
+        }>;
+    };
+}
+/**
+ * CDP `consoleAPICalled.type` → our console level. CDP emits `'warning'` where
+ * we use `'warn'`; every other known level passes through; anything else (e.g.
+ * `'dir'`, `'table'`, `'trace'`, `undefined`) maps to `'log'`.
+ */
+export declare function mapConsoleApiType(type: string | undefined): ConsoleLevel;
+/**
+ * A single RemoteObject → a JSON-serializable value WITHOUT a CDP round-trip
+ * (shallow). Objects that need their full contents are flagged by
+ * {@link needsDeepFetch} and deep-serialized by the caller; this is the
+ * inline/best-effort fallback.
+ */
+export declare function remoteObjectToValue(ro: RemoteObjectLike): unknown;
+/**
+ * Whether this RemoteObject must be deep-fetched via `Runtime.callFunctionOn`
+ * (returnByValue) to be fully serialized — i.e. a real object/array referenced
+ * by `objectId` with no inline `value`. Functions, primitives, `null`, and
+ * already-inlined values do not.
+ */
+export declare function needsDeepFetch(ro: RemoteObjectLike): boolean;
+/**
+ * True when a `consoleAPICalled` event is the render→service `[视图]`
+ * re-injection (its top call frame URL === the sentinel) and must NOT be
+ * re-forwarded — the original render entry already reached every consumer.
+ */
+export declare function isRenderForwardEvent(params: ConsoleApiParamsLike, sentinelUrl: string): boolean;
+//# sourceMappingURL=console-api.d.ts.map

package/dist/main/services/service-console/console-api.js

@@ -0,0 +1,104 @@
+/**
+ * Pure helpers for the native-host service-console forwarder.
+ *
+ * Under native-host the service-host's console used to be captured by a
+ * `console.*` monkeypatch in `service-host/preload.cjs`. That wrapper added a
+ * stack frame, so Chrome DevTools (attached natively to the service host)
+ * attributed EVERY service-layer log to the wrapper line (`preload.cjs:237`)
+ * instead of the developer's source. We now capture via CDP
+ * `Runtime.consoleAPICalled` instead, which preserves native source attribution.
+ *
+ * These functions turn the CDP event shape into the `GuestConsoleEntry` shape
+ * the existing console fan-out (automation `App.logAdded`) expects, WITHOUT any
+ * electron / IO dependency so they are unit-testable in isolation. The async
+ * deep-fetch (`Runtime.callFunctionOn`) for object args lives in `index.ts`.
+ */
+/**
+ * sourceURL stamped on the render→service `[视图]` re-injection script
+ * (`console-forward.buildForwardScript`). The CDP capture skips any
+ * `consoleAPICalled` whose top frame carries this URL so a forwarded render line
+ * is not re-captured and re-broadcast as a service entry (duplicate / loop).
+ */
+export const RENDER_FORWARD_SOURCE_URL = 'dimina://render-console-forward';
+const KNOWN_LEVELS = new Set(['log', 'warn', 'error', 'info', 'debug']);
+/**
+ * CDP `consoleAPICalled.type` → our console level. CDP emits `'warning'` where
+ * we use `'warn'`; every other known level passes through; anything else (e.g.
+ * `'dir'`, `'table'`, `'trace'`, `undefined`) maps to `'log'`.
+ */
+export function mapConsoleApiType(type) {
+    if (type === 'warning')
+        return 'warn';
+    if (type && KNOWN_LEVELS.has(type))
+        return type;
+    return 'log';
+}
+const BIGINT_LITERAL = /^-?\d+n$/;
+/**
+ * A single RemoteObject → a JSON-serializable value WITHOUT a CDP round-trip
+ * (shallow). Objects that need their full contents are flagged by
+ * {@link needsDeepFetch} and deep-serialized by the caller; this is the
+ * inline/best-effort fallback.
+ */
+export function remoteObjectToValue(ro) {
+    if (!ro)
+        return ro;
+    // 1. An inlined value (CDP includes `value` for JSON-serializable primitives
+    //    and small arrays). Use `in` so falsy values (0, '', false) and an
+    //    explicit `null` are honoured rather than falling through.
+    if ('value' in ro)
+        return ro.value;
+    // 2. Specials that can't ride in `value`.
+    if (typeof ro.unserializableValue === 'string') {
+        const u = ro.unserializableValue;
+        if (u === 'Infinity')
+            return Infinity;
+        if (u === '-Infinity')
+            return -Infinity;
+        if (u === 'NaN')
+            return NaN;
+        if (u === '-0')
+            return -0;
+        if (BIGINT_LITERAL.test(u))
+            return u;
+        return u;
+    }
+    // 3. Fall back by type.
+    switch (ro.type) {
+        case 'undefined':
+            return undefined;
+        case 'function':
+            return ro.description ?? '[Function]';
+        case 'symbol':
+            return ro.description ?? '[Symbol]';
+        case 'object':
+            if (ro.subtype === 'null')
+                return null;
+            return ro.description ?? '[Object]';
+        default:
+            return ro.description ?? '[Unknown]';
+    }
+}
+/**
+ * Whether this RemoteObject must be deep-fetched via `Runtime.callFunctionOn`
+ * (returnByValue) to be fully serialized — i.e. a real object/array referenced
+ * by `objectId` with no inline `value`. Functions, primitives, `null`, and
+ * already-inlined values do not.
+ */
+export function needsDeepFetch(ro) {
+    if (!ro)
+        return false;
+    if ('value' in ro)
+        return false;
+    return ro.type === 'object' && ro.subtype !== 'null' && typeof ro.objectId === 'string';
+}
+/**
+ * True when a `consoleAPICalled` event is the render→service `[视图]`
+ * re-injection (its top call frame URL === the sentinel) and must NOT be
+ * re-forwarded — the original render entry already reached every consumer.
+ */
+export function isRenderForwardEvent(params, sentinelUrl) {
+    const top = params?.stackTrace?.callFrames?.[0]?.url;
+    return typeof top === 'string' && top === sentinelUrl;
+}
+//# sourceMappingURL=console-api.js.map

package/dist/main/services/service-console/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Native-host SERVICE-layer console capture via CDP.
+ *
+ * The embedded Chrome DevTools front-end is attached natively to the service
+ * host, so the service layer's `console.*` already displays there with correct
+ * source attribution + sourcemaps — UNLESS something rewrites `console.*`. The
+ * old `service-host/preload.cjs` monkeypatch did exactly that (wrapping each
+ * level to also post the entry to main), which made DevTools attribute every
+ * service log to the wrapper line (`preload.cjs:237`) instead of the developer's
+ * source. That monkeypatch is removed; this service replaces its ONE remaining
+ * job — feeding service-layer entries to the console fan-out (automation
+ * `App.logAdded`) — by capturing `Runtime.consoleAPICalled` over an in-process
+ * CDP session instead. Capturing at the CDP layer adds no stack frame, so native
+ * attribution in the DevTools console is preserved (verified: an in-process
+ * `debugger.attach('1.3')` coexists with the custom-host DevTools front-end on
+ * the same wc — Electron multi-client CDP).
+ *
+ * Lifecycle: installed when the right-panel DevTools is pointed at a service host
+ * wc (`view-manager.pointNativeDevtoolsAtServiceWc`) and stopped when that source
+ * is closed / swapped (pre-warm pool recycles the service window). `stop()` is
+ * idempotent.
+ */
+import type { WebContents } from 'electron';
+import type { ConnectionRegistry } from '@dimina-kit/electron-deck/main';
+import type { GuestConsoleEntry } from '../console-forward/index.js';
+export interface ServiceConsoleForwardDeps {
+    /** The service host wc whose `console.*` we capture (top-level BrowserWindow wc). */
+    serviceWc: WebContents;
+    /** Sink for each captured service entry (wired to `consoleForwarder.emit`). */
+    emit: (entry: GuestConsoleEntry) => void;
+    /** Connection registry — binds teardown to the service wc's destroy ('closed'). */
+    connections?: ConnectionRegistry;
+}
+export interface ServiceConsoleForwardHandle {
+    /** Detach the CDP session (if we attached it) and stop capturing. Idempotent. */
+    stop(): void;
+}
+/**
+ * Attach an in-process CDP session to `serviceWc`, enable Runtime, and forward
+ * every `Runtime.consoleAPICalled` to `emit` as a `source:'service'` entry —
+ * EXCEPT the render→service `[视图]` re-injection (skipped via sentinel so it is
+ * not double-broadcast). Object args are deep-serialized via
+ * `Runtime.callFunctionOn` on our OWN session (the objectId can't be released by
+ * the front-end), falling back to the shallow inline value on failure.
+ */
+export declare function installServiceConsoleForward(deps: ServiceConsoleForwardDeps): ServiceConsoleForwardHandle;
+//# sourceMappingURL=index.d.ts.map

package/dist/main/services/service-console/index.js

@@ -0,0 +1,139 @@
+import { RENDER_FORWARD_SOURCE_URL, mapConsoleApiType, needsDeepFetch, remoteObjectToValue, isRenderForwardEvent, } from './console-api.js';
+/**
+ * Attach an in-process CDP session to `serviceWc`, enable Runtime, and forward
+ * every `Runtime.consoleAPICalled` to `emit` as a `source:'service'` entry —
+ * EXCEPT the render→service `[视图]` re-injection (skipped via sentinel so it is
+ * not double-broadcast). Object args are deep-serialized via
+ * `Runtime.callFunctionOn` on our OWN session (the objectId can't be released by
+ * the front-end), falling back to the shallow inline value on failure.
+ */
+export function installServiceConsoleForward(deps) {
+    const { serviceWc, emit, connections } = deps;
+    let disposed = false;
+    // Did WE attach the session (vs. it already being attached by someone else)?
+    // Only detach what we own.
+    let selfAttached = false;
+    // Process events in arrival order even though arg resolution is async, so the
+    // forwarded sequence matches the order the developer logged.
+    let tail = Promise.resolve();
+    let closedSub;
+    function usableDebugger() {
+        try {
+            if (serviceWc.isDestroyed())
+                return false;
+            if (serviceWc.debugger.isAttached())
+                return true;
+        }
+        catch {
+            return false;
+        }
+        try {
+            serviceWc.debugger.attach('1.3');
+            selfAttached = true;
+            return true;
+        }
+        catch {
+            // Race: someone attached between the check and here → still usable.
+            try {
+                return serviceWc.debugger.isAttached();
+            }
+            catch {
+                return false;
+            }
+        }
+    }
+    /** Deep-serialize one arg; best-effort, never throws. */
+    async function resolveArg(ro) {
+        if (!needsDeepFetch(ro))
+            return remoteObjectToValue(ro);
+        try {
+            const res = (await serviceWc.debugger.sendCommand('Runtime.callFunctionOn', {
+                objectId: ro.objectId,
+                functionDeclaration: 'function () { return this }',
+                returnByValue: true,
+            }));
+            if (res && res.result && 'value' in res.result)
+                return res.result.value;
+        }
+        catch {
+            // Object released / host navigating — fall back to the shallow value.
+        }
+        return remoteObjectToValue(ro);
+    }
+    async function handleConsoleApi(params) {
+        if (disposed)
+            return;
+        // Skip the render→service `[视图]` re-injection — the original render entry
+        // already reached every consumer; re-forwarding would duplicate it.
+        if (isRenderForwardEvent(params, RENDER_FORWARD_SOURCE_URL))
+            return;
+        const level = mapConsoleApiType(params.type);
+        const rawArgs = Array.isArray(params.args) ? params.args : [];
+        let args;
+        try {
+            args = await Promise.all(rawArgs.map((a) => resolveArg(a)));
+        }
+        catch {
+            args = rawArgs.map((a) => remoteObjectToValue(a));
+        }
+        if (disposed)
+            return;
+        emit({ source: 'service', level, args, ts: Date.now() });
+    }
+    const onMessage = (_event, method, params) => {
+        if (disposed)
+            return;
+        if (method !== 'Runtime.consoleAPICalled')
+            return;
+        const p = params;
+        tail = tail.then(() => handleConsoleApi(p)).catch(() => { });
+    };
+    function stop() {
+        if (disposed)
+            return;
+        disposed = true;
+        try {
+            closedSub?.dispose();
+        }
+        catch { /* gone */ }
+        try {
+            serviceWc.debugger.removeListener('message', onMessage);
+        }
+        catch { /* gone */ }
+        if (selfAttached) {
+            try {
+                if (!serviceWc.isDestroyed() && serviceWc.debugger.isAttached())
+                    serviceWc.debugger.detach();
+            }
+            catch { /* already detached / destroyed */ }
+            selfAttached = false;
+        }
+    }
+    if (!usableDebugger()) {
+        disposed = true;
+        return { stop() { } };
+    }
+    try {
+        serviceWc.debugger.on('message', onMessage);
+    }
+    catch {
+        stop();
+        return { stop() { } };
+    }
+    // Enable Runtime so consoleAPICalled flows. Best-effort — a mid-destroy host
+    // rejects, in which case there's simply nothing to capture.
+    serviceWc.debugger.sendCommand('Runtime.enable').catch(() => { });
+    // Bind teardown to the service wc's real destroy. The service window is
+    // pool-recycled, but 'closed' fires only on hard destroy — the right lifetime
+    // for a session we attached to THIS wc. `on('closed')` returns a handle whose
+    // dispose() removes the listener WITHOUT firing it.
+    try {
+        if (connections)
+            closedSub = connections.acquire(serviceWc).on('closed', stop);
+        else
+            serviceWc.once('destroyed', stop);
+    }
+    catch { /* fake/minimal wc in tests */ }
+    return { stop };
+}
+//# sourceMappingURL=index.js.map

package/dist/main/services/update/update-manager.d.ts

@@ -26,7 +26,7 @@ export declare class UpdateManager {
     private downloadedPath;
     /**
      * Whether this instance has already emitted `Available` once. The periodic
-     * check fires forever (interval default 1h), and downstream UI (qdmp shell
+     * check fires forever (interval default 1h), and downstream UI (a downstream host shell
      * renders a native toast / Notification) is not idempotent — every event
      * stacks. We dedupe at the source: at most one Available per instance
      * lifetime, regardless of how the upstream `info.version` shifts. The user

package/dist/main/services/update/update-manager.js

@@ -9,7 +9,7 @@ export class UpdateManager {
     downloadedPath = null;
     /**
      * Whether this instance has already emitted `Available` once. The periodic
-     * check fires forever (interval default 1h), and downstream UI (qdmp shell
+     * check fires forever (interval default 1h), and downstream UI (a downstream host shell
      * renders a native toast / Notification) is not idempotent — every event
      * stacks. We dedupe at the source: at most one Available per instance
      * lifetime, regardless of how the upstream `info.version` shifts. The user

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

@@ -34,6 +34,13 @@ export interface ViewManagerContext {
      * console line is the fallback). Optional so partial test contexts compile.
      */
     networkForward?: WorkbenchContext['networkForward'];
+    /**
+     * Always-on console fan-out (set by `installBridgeRouter`). The service-console
+     * capture feeds service-layer `consoleAPICalled` entries here so they reach
+     * automation; mirrors how render entries arrive via the bridge. Optional so
+     * partial test contexts compile.
+     */
+    consoleForwarder?: WorkbenchContext['consoleForwarder'];
     /**
      * Per-context registry of host-registered simulator custom APIs. The
      * native-host simulator is a top-level WebContentsView with no embedder

package/dist/main/services/views/view-manager.js

@@ -8,6 +8,7 @@ import { OPEN_IN_EDITOR_SCHEME, decodeOpenInEditorUrl, resourceUrlToProjectRelat
 import { createSafeAreaController } from '../safe-area/index.js';
 import { buildCustomizeTabsScript } from './devtools-tabs.js';
 import { installElementsForward } from '../elements-forward/index.js';
+import { installServiceConsoleForward } from '../service-console/index.js';
 import * as layout from '../layout/index.js';
 import { handleCustomApiBridgeRequest, } from '../simulator/custom-apis.js';
 import { configureMiniappSession, miniappPartition } from './miniapp-partition.js';
@@ -72,6 +73,10 @@ export function createViewManager(ctx) {
     // CDP traffic at the active render guest). Installed in
     // `attachNativeSimulatorDevtoolsHost`, stopped on detach / host destroyed.
     let stopElementsForward = null;
+    // Disposer for the service-layer console capture (CDP `consoleAPICalled` on the
+    // service host wc → console fan-out). Installed when the DevTools is pointed at
+    // a service host, stopped when that source is closed / swapped.
+    let stopServiceConsole = null;
     let nativeDevtoolsRetryTimer = null;
     let nativeDevtoolsRetryToken = 0;
     // Renderer-driven overlay bounds for the simulator DevTools view — the SOLE
@@ -152,6 +157,9 @@ export function createViewManager(ctx) {
         if (!simulatorViewAdded) {
             ctx.windows.mainWindow.contentView.addChildView(simulatorView);
             simulatorViewAdded = true;
+            // Re-attaching this base overlay moved it to the top of the z-stack; keep
+            // any open settings/popover above it.
+            raiseTopOverlays();
         }
         simulatorView.setBounds(bounds);
     }
@@ -386,6 +394,11 @@ export function createViewManager(ctx) {
     function closeNativeDevtoolsSource() {
         const source = nativeDevtoolsSourceWc;
         nativeDevtoolsSourceWc = null;
+        try {
+            stopServiceConsole?.();
+        }
+        catch { /* already stopped */ }
+        stopServiceConsole = null;
         if (!source || source.isDestroyed())
             return;
         try {
@@ -557,6 +570,19 @@ export function createViewManager(ctx) {
             // Re-applied on every re-point so a service-host pool swap (fresh
             // openDevTools) re-asserts the custom tab bar.
             customizeDevtoolsTabs(simulatorView.webContents);
+            // Capture service-layer console via CDP (NOT a preload monkeypatch, which
+            // would clobber native source attribution) and feed it to the console
+            // fan-out (automation `App.logAdded`). Bound to THIS service wc; replaced
+            // on the next re-point via closeNativeDevtoolsSource.
+            try {
+                stopServiceConsole?.();
+            }
+            catch { /* already stopped */ }
+            stopServiceConsole = installServiceConsoleForward({
+                serviceWc: next,
+                connections: ctx.connections,
+                emit: (entry) => ctx.consoleForwarder?.emit(entry),
+            }).stop;
             return true;
         }
         catch {
@@ -1038,6 +1064,11 @@ export function createViewManager(ctx) {
             // Overlay loads mainPreloadPath, so the same navigation rules as the
             // main window apply — see navigation-hardening.ts.
             applyNavigationHardening(settingsView.webContents, ctx.rendererDir);
+            // Transparent backing: the settings view now spans the whole content area
+            // (computeSettingsBounds) and its renderer paints a transparent backdrop +
+            // an opaque right-side panel, so the underlying editor/simulator show
+            // through and a backdrop click closes the overlay (mirrors the popover).
+            settingsView.setBackgroundColor('#00000000');
             await settingsView.webContents.loadFile(path.join(ctx.rendererDir, 'entries/settings/index.html'));
         }
         if (!settingsViewAdded) {
@@ -1055,6 +1086,25 @@ export function createViewManager(ctx) {
             settingsViewAdded = false;
         }
     }
+    // Keep the TOP-tier overlays (settings, popover) above the BASE-tier native
+    // overlays (the native simulator WCV + the console/DevTools WCV). Native
+    // overlays are z-ordered by `addChildView` insertion order — the last-added
+    // sits on top — so RE-attaching a base overlay while a top overlay is open
+    // (e.g. the simulator re-shows on a tab switch, or the console bounds
+    // republish re-adds it) would move the base ABOVE the open settings/popover
+    // and occlude it. Whenever a base overlay is (re)added, re-append the open top
+    // overlays so they stay on top. Settings is re-appended before popover so a
+    // simultaneously-open popover ends up topmost. A no-op when neither is open
+    // (pinned by the z-order guard test).
+    function raiseTopOverlays() {
+        if (ctx.windows.mainWindow.isDestroyed())
+            return;
+        const cv = ctx.windows.mainWindow.contentView;
+        if (settingsView && settingsViewAdded)
+            cv.addChildView(settingsView);
+        if (popoverView)
+            cv.addChildView(popoverView);
+    }
     function showPopover(data) {
         hidePopover();
         const popover = new WebContentsView({
@@ -1141,6 +1191,9 @@ export function createViewManager(ctx) {
         if (!nativeSimulatorViewAdded) {
             ctx.windows.mainWindow.contentView.addChildView(nativeSimulatorView);
             nativeSimulatorViewAdded = true;
+            // Re-attaching this base overlay moved it to the top of the z-stack; keep
+            // any open settings/popover above it.
+            raiseTopOverlays();
         }
         nativeSimulatorView.setBounds(p.bounds);
         const simWc = nativeSimulatorView.webContents;

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

@@ -137,12 +137,13 @@ export interface WorkbenchContext {
      */
     storageApi?: StorageApi;
     /**
-     * Native-host console sink. The render-host / service-host guest preloads
-     * monkeypatch `console.*` and post each entry to main as a `consoleLog`
-     * container message; bridge-router routes those here. Owned by the
-     * `ConsoleForwarder` (set in `installBridgeRouter`), whose `emit` fans every
-     * entry out to subscribers (automation WS) AND mirrors render-layer entries
-     * into the service host's own console for the embedded DevTools.
+     * Native-host console sink. Render-layer entries arrive from
+     * render-host/preload.cjs (`console.*` monkeypatch → `consoleLog` message);
+     * service-layer entries arrive from CDP `Runtime.consoleAPICalled`
+     * (services/service-console) so native source attribution is preserved.
+     * Owned by the `ConsoleForwarder` (set in `installBridgeRouter`), whose `emit`
+     * fans every entry out to subscribers (automation WS) AND mirrors render-layer
+     * entries into the service host's own console for the embedded DevTools.
      */
     guestConsole?: {
         emit(entry: unknown): void;