@dimina-kit/devtools 0.4.0-dev.20260718143821 → 0.4.0-dev.20260728063215

package/dist/main/services/views/native-simulator-devtools-host.js

@@ -1,6 +1,8 @@
-import { WebContentsView } from 'electron';
+import { WebContentsView, webContents as electronWebContents } from 'electron';
 import { buildDevtoolsProjectSourceLinksScript, decodeOpenInEditorUrl, projectSourceContextFromServiceHostUrl, } from '../../../shared/open-in-editor.js';
 import { buildCustomizeTabsScript } from './devtools-tabs.js';
+import { buildConsoleFilterScript, buildLiveConsoleFilterScript } from './console-filter.js';
+import { whenFrontendBootstrapped } from './frontend-bootstrap-gate.js';
 import { installElementsForward } from '../elements-forward/index.js';
 import { installServiceConsoleForward } from '../service-console/index.js';
 import { VIEW_ID } from '../../../shared/view-ids.js';
@@ -54,6 +56,7 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
     // (`rebuildDevtoolsHostView`) rather than target it again.
     let devtoolsHostUsed = false;
     let unsubscribeNativeRenderEvents = null;
+    let unsubscribeNativeServiceHostReady = null;
     // Disposer for the Elements-forward feature (routes the front-end's Elements
     // CDP traffic at the active render guest). Installed in
     // `attach`, stopped on detach / host destroyed.
@@ -106,6 +109,13 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
             catch { /* ignore */ }
             unsubscribeNativeRenderEvents = null;
         }
+        if (unsubscribeNativeServiceHostReady) {
+            try {
+                unsubscribeNativeServiceHostReady();
+            }
+            catch { /* ignore */ }
+            unsubscribeNativeServiceHostReady = null;
+        }
         closeNativeDevtoolsSource();
     }
     function injectOpenResourceHandler(serviceWc, devtoolsWc) {
@@ -158,6 +168,39 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
         }
         catch { /* wc surface incomplete / torn down; degrade silently */ }
     }
+    // User-facing Console de-noise: hide dimina
+    // framework internal log lines from THIS right-panel Console — the
+    // standalone internal DevTools window (native-only, wired elsewhere) shows
+    // them unfiltered. Re-applied on every re-point, same policy as
+    // customizeDevtoolsTabs. Runs BOTH the persisted-preference write (for a
+    // not-yet-constructed panel) AND the live-object drive (for a panel that's
+    // already constructed by the time this injection lands, or finishes
+    // constructing shortly after — see console-filter.ts's header comment for
+    // why the persisted write alone cannot cover that case).
+    // Bootstrap-gated: the live script touches `Console.ConsoleView.instance()`,
+    // which — fired before the front-end's own bootstrap completes —
+    // constructs IssuesManager early and permanently kills that bootstrap (see
+    // frontend-bootstrap-gate.ts). Gate resolving false = degrade silently,
+    // this module's standing convention.
+    function applyConsoleFilter(devtoolsWc) {
+        try {
+            if (devtoolsWc.isDestroyed())
+                return;
+            const inject = () => {
+                void whenFrontendBootstrapped(devtoolsWc).then((ready) => {
+                    if (!ready || devtoolsWc.isDestroyed())
+                        return;
+                    try {
+                        void devtoolsWc.executeJavaScript(buildConsoleFilterScript()).catch(() => { });
+                        void devtoolsWc.executeJavaScript(buildLiveConsoleFilterScript()).catch(() => { });
+                    }
+                    catch { /* wc torn down mid-call */ }
+                });
+            };
+            injectWhenReady(devtoolsWc, 'console-filter', inject);
+        }
+        catch { /* wc surface incomplete / torn down; degrade silently */ }
+    }
     function wireOpenInEditor(serviceWc, devtoolsWc) {
         // Inject the front-end handler on every (re)attach — the DevTools front-end
         // wc is recreated per simulatorView, so a fresh host needs the handler set.
@@ -246,6 +289,9 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
             // Re-applied on every re-point so a service-host pool swap (fresh
             // openDevTools) re-asserts the custom tab bar.
             customizeDevtoolsTabs(simulatorView.webContents);
+            // De-noise the user-facing Console: hide
+            // dimina framework internal log lines from THIS panel by default.
+            applyConsoleFilter(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
@@ -286,8 +332,25 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
             return false;
         return pointNativeDevtoolsAtServiceWc(wc);
     }
-    function scheduleNativeDevtoolsFollow(appId, attempt = 0) {
-        if (attempt >= 20)
+    // Bound on how long the FALLBACK poll (below) keeps retrying before giving
+    // up — a pure safety valve, not the real mechanism. The real mechanism is
+    // `onNativeServiceHostReady` (an event, not a poll): it fires the moment
+    // `ctx.bridge.getServiceWc` is GUARANTEED to resolve, so this fallback only
+    // exists for the residual gap where `followNativeDevtoolsServiceHost` runs
+    // from a render event that races ahead of that event somehow. A fixed short
+    // attempt count here (originally 20×50ms = 1s) was the actual production
+    // bug this module was fixed for: under real machine load,
+    // `ctx.bridge.getServiceWc(appId)` can take longer than 1s to resolve, and
+    // once the fixed budget ran out the right-panel DevTools attach was
+    // silently, permanently lost for the rest of that session (confirmed via
+    // real reproduction + timing instrumentation). Bounded by WALL-CLOCK time
+    // (generous — normal resolution is well under a second) rather than a
+    // small attempt count, since the fallback's whole job is to outlast a slow
+    // machine, not a slow algorithm.
+    const NATIVE_DEVTOOLS_FALLBACK_POLL_MAX_MS = 60_000;
+    const NATIVE_DEVTOOLS_FALLBACK_POLL_INTERVAL_MS = 50;
+    function scheduleNativeDevtoolsFollow(appId, startedAt = Date.now()) {
+        if (Date.now() - startedAt >= NATIVE_DEVTOOLS_FALLBACK_POLL_MAX_MS)
             return;
         if (!ctx.bridge?.isNativeHost())
             return;
@@ -300,8 +363,8 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
                 return;
             if (pointNativeDevtoolsAtActiveServiceHost(appId))
                 return;
-            scheduleNativeDevtoolsFollow(appId, attempt + 1);
-        }, 50);
+            scheduleNativeDevtoolsFollow(appId, startedAt);
+        }, NATIVE_DEVTOOLS_FALLBACK_POLL_INTERVAL_MS);
     }
     function followNativeDevtoolsServiceHost(appId) {
         clearNativeDevtoolsRetry();
@@ -309,10 +372,53 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
             return;
         scheduleNativeDevtoolsFollow(appId);
     }
+    // The real mechanism: fires the moment a service host's `service.html`
+    // did-finish-load's, i.e. the exact instant `serviceWcId` is guaranteed
+    // resolvable — no polling, no race against a fixed retry budget. Resolves
+    // the wc DIRECTLY via the id the event carries (never re-resolving through
+    // `getServiceWc(appId)`, which during same-app respawn overlap returns the
+    // newest session, not necessarily the one that fired this event), then
+    // validates the event against that same authority before acting — see the
+    // generation gate below.
+    function onNativeServiceHostReady(event) {
+        if (!ctx.bridge?.isNativeHost())
+            return;
+        if (!simulatorView || simulatorView.webContents.isDestroyed())
+            return;
+        const wc = electronWebContents.fromId(event.serviceWcId);
+        if (!wc || wc.isDestroyed())
+            return;
+        // Generation gate: `getServiceWc` resolves the NEWEST live session
+        // (bridge-router's findAppSessionByAppId is last-inserted-wins), so an
+        // event it CONTRADICTS is a superseded session's late-arriving ready —
+        // repointing there would resurrect a dying host (the newer session's own
+        // ready does/did the real repoint). An authority that cannot resolve at
+        // all fails OPEN: the event is the only signal available, and dropping
+        // it would strand the attach on nothing. Fail-open cannot stick to a
+        // dying wc in practice — the direct emit is same-tick with bootServiceHost
+        // (session still registered), the catch-up path re-validates the session
+        // before delivering, and even a hypothetical miss just makes point()
+        // return false into the wall-clock-bounded fallback.
+        const current = ctx.bridge.getServiceWc(event.appId);
+        if (current && current.id !== event.serviceWcId)
+            return;
+        // Only a SUCCESSFUL repoint may retire the standing fallback poll — a
+        // failed attempt (service wc torn down mid-point is the common race)
+        // must leave/re-arm it, or this very event cancels the retry that would
+        // have eventually attached.
+        if (pointNativeDevtoolsAtServiceWc(wc)) {
+            clearNativeDevtoolsRetry();
+            return;
+        }
+        scheduleNativeDevtoolsFollow(event.appId);
+    }
     // Render-side activity (a page DOM mounting / the visible page changing)
     // always follows a spawn or respawn, by which point the service window exists
     // (and may have been swapped by the pool). Re-resolve + re-point the DevTools
-    // at the now-current service host on every such event.
+    // at the now-current service host on every such event. Belt-and-suspenders
+    // alongside `onNativeServiceHostReady` — by the time a render event fires,
+    // the service host that produced it is definitionally already resolvable,
+    // so this path should normally resolve immediately (no fallback poll needed).
     function onNativeRenderEvent(event) {
         if (event.kind !== 'activePage' && event.kind !== 'domReady')
             return;
@@ -341,11 +447,17 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
         // Default DevTools to Console panel (Chrome DevTools defaults to Elements).
         // The DevTools UI lives inside closed shadow roots, so a light-DOM
         // querySelector('[role="tab"]') cannot reach the tab bar to click it.
-        // Instead drive the front-end's own view manager: the bundled DevTools
-        // exposes `UI.ViewManager.instance().showView(id)` on `globalThis.UI`
-        // once the front-end has finished bootstrapping. We poll for it and
-        // request the `console` view, and also persist the choice via the
-        // `panel-selectedTab` localStorage key so subsequent reloads honor it.
+        // Instead drive the front-end's own view manager via `globalThis.EUI`
+        // (the bundle's real exposure of the ui/legacy namespace) — NOT
+        // `globalThis.UI`, which never exists on this front-end build (same
+        // finding devtools-tabs.ts records; an earlier `UI.…`-polling version of
+        // this script was dead code and the panel silently defaulted to
+        // Elements). Gated on frontend bootstrap: `ViewManager.instance()` is a
+        // singleton construction, only safe after the front-end's own MainImpl
+        // finished wiring (see frontend-bootstrap-gate.ts). (A persisted
+        // `panel-selected-tab` preference write is NOT an alternative mechanism —
+        // this custom devtools:// host persists nothing to disk; see
+        // console-filter.ts's header.)
         const devtoolsWc = simulatorView.webContents;
         // The boot-time burst of `executeJavaScript()` injects on this host wc (tab
         // customization / console default / Elements+Network forwarding below) each
@@ -400,27 +512,22 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
             });
         }
         injectWhenReady(devtoolsWc, 'console-default', () => {
-            devtoolsWc.executeJavaScript(`
-        (function() {
-          try { localStorage.setItem('panel-selectedTab', '"console"') } catch {}
-          let tries = 0
-          const timer = setInterval(() => {
-            tries++
+            void whenFrontendBootstrapped(devtoolsWc).then((ready) => {
+                if (!ready || devtoolsWc.isDestroyed())
+                    return;
+                devtoolsWc.executeJavaScript(`
+          (function() {
             try {
-              const UI = globalThis.UI
-              const vm = UI && UI.ViewManager && typeof UI.ViewManager.instance === 'function'
-                ? UI.ViewManager.instance()
+              var EUI = globalThis.EUI
+              var vm = EUI && EUI.ViewManager && EUI.ViewManager.ViewManager
+                && typeof EUI.ViewManager.ViewManager.instance === 'function'
+                ? EUI.ViewManager.ViewManager.instance()
                 : null
-              if (vm && typeof vm.showView === 'function') {
-                vm.showView('console')
-                clearInterval(timer)
-                return
-              }
-            } catch {}
-            if (tries > 80) clearInterval(timer)
-          }, 50)
-        })()
-      `).catch(() => { });
+              if (vm && typeof vm.showView === 'function') void vm.showView('console')
+            } catch (_) {}
+          })()
+        `).catch(() => { });
+            });
         });
         // Anchor-only mount: the renderer's published rect is the SOLE authority.
         // If a non-zero rect was already published (it can land before this attach
@@ -440,6 +547,7 @@ export function createDevtoolsHost(ctx, reconciler, deps) {
         rebuildDevtoolsHostView();
         if (ctx.bridge?.isNativeHost()) {
             unsubscribeNativeRenderEvents = ctx.bridge.onRenderEvent(onNativeRenderEvent);
+            unsubscribeNativeServiceHostReady = ctx.bridge.onServiceHostReady(onNativeServiceHostReady);
             followNativeDevtoolsServiceHost();
         }
     }

package/dist/main/services/views/view-manager-devtools-host-test-fixtures.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared harness for the simulator-DevTools host suites
+ * (`view-manager-devtools-host-repoint.test.ts` +
+ * `view-manager-service-host-ready.test.ts`), split out so each test file
+ * stays under the repo's 500-line-per-file ratchet. Pure test scaffolding,
+ * not code under test — same pattern as
+ * network-forward/global-mirror-test-fixtures.ts.
+ *
+ * Consumers register the module mocks themselves (vi.mock factories are
+ * hoisted per test file, so they live there, thin):
+ *   vi.mock('electron', async () =>
+ *     (await import('./view-manager-devtools-host-test-fixtures.js')).electronModuleMock())
+ *   vi.mock('../../utils/paths.js', async () =>
+ *     (await import('./view-manager-devtools-host-test-fixtures.js')).pathsModuleMock())
+ * The electron factory closes over this module's `constructed` /
+ * `serviceWcRegistry` registries, so test assertions and the mock see the
+ * same objects (vitest gives each test FILE its own instance of this module —
+ * no cross-file bleed).
+ */
+import { vi } from 'vitest';
+import type { RenderEvent, ServiceHostReadyEvent } from '../../ipc/bridge-router.js';
+import type { ViewManagerContext } from './view-manager.js';
+export type StubWebContents = {
+    destroyed: boolean;
+    id: number;
+    isDestroyed: () => boolean;
+    close: ReturnType<typeof vi.fn>;
+    loadURL: ReturnType<typeof vi.fn>;
+    loadFile: ReturnType<typeof vi.fn>;
+    on: ReturnType<typeof vi.fn>;
+    once: ReturnType<typeof vi.fn>;
+    removeListener: ReturnType<typeof vi.fn>;
+    setWindowOpenHandler: ReturnType<typeof vi.fn>;
+    setZoomFactor: ReturnType<typeof vi.fn>;
+    send: ReturnType<typeof vi.fn>;
+    setMaxListeners: ReturnType<typeof vi.fn>;
+    getMaxListeners: ReturnType<typeof vi.fn>;
+    isLoading: ReturnType<typeof vi.fn>;
+    executeJavaScript: ReturnType<typeof vi.fn>;
+    setDevToolsWebContents: ReturnType<typeof vi.fn>;
+    openDevTools: ReturnType<typeof vi.fn>;
+    isDevToolsOpened: ReturnType<typeof vi.fn>;
+    closeDevTools: ReturnType<typeof vi.fn>;
+    getURL: ReturnType<typeof vi.fn>;
+};
+export type StubView = {
+    webContents: StubWebContents;
+    setBounds: ReturnType<typeof vi.fn>;
+    setBackgroundColor: ReturnType<typeof vi.fn>;
+};
+/** Every WebContentsView ever constructed by the code under test, in
+ * construction order: attachNativeSimulator builds [0] = the native simulator
+ * content view, then attachNativeSimulatorDevtoolsHost builds [1] = the
+ * DevTools front-end host view. Reset in each file's beforeEach. */
+export declare const constructed: StubView[];
+/** Service-host wcs registered by `makeServiceWc`, looked up by
+ * `electron.webContents.fromId` — mirrors real Electron's global wc registry
+ * so `onNativeServiceHostReady`'s `webContents.fromId(event.serviceWcId)`
+ * resolution has something real to find. */
+export declare const serviceWcRegistry: Map<number, StubWebContents>;
+/** The `electron` module surface view-manager and its injectors touch. */
+export declare function electronModuleMock(): Record<string, unknown>;
+export declare function pathsModuleMock(): Record<string, unknown>;
+export declare const SIM_URL = "http://localhost:7788/simulator.html?appId=repoint";
+/** A hidden SERVICE-HOST BrowserWindow wc (top-level, can host DevTools). */
+export declare function makeServiceWc(id: number): StubWebContents;
+export interface DevtoolsHostHarness {
+    addChildView: ReturnType<typeof vi.fn>;
+    removeChildView: ReturnType<typeof vi.fn>;
+    setActiveServiceWc: (wc: StubWebContents) => void;
+    emitRenderEvent: (event: RenderEvent) => void;
+    emitServiceHostReady: (event: ServiceHostReadyEvent) => void;
+    ctx: ViewManagerContext;
+}
+export declare function makeContext(): DevtoolsHostHarness;
+//# sourceMappingURL=view-manager-devtools-host-test-fixtures.d.ts.map

package/dist/main/services/views/view-manager-devtools-host-test-fixtures.js

@@ -0,0 +1,182 @@
+/**
+ * Shared harness for the simulator-DevTools host suites
+ * (`view-manager-devtools-host-repoint.test.ts` +
+ * `view-manager-service-host-ready.test.ts`), split out so each test file
+ * stays under the repo's 500-line-per-file ratchet. Pure test scaffolding,
+ * not code under test — same pattern as
+ * network-forward/global-mirror-test-fixtures.ts.
+ *
+ * Consumers register the module mocks themselves (vi.mock factories are
+ * hoisted per test file, so they live there, thin):
+ *   vi.mock('electron', async () =>
+ *     (await import('./view-manager-devtools-host-test-fixtures.js')).electronModuleMock())
+ *   vi.mock('../../utils/paths.js', async () =>
+ *     (await import('./view-manager-devtools-host-test-fixtures.js')).pathsModuleMock())
+ * The electron factory closes over this module's `constructed` /
+ * `serviceWcRegistry` registries, so test assertions and the mock see the
+ * same objects (vitest gives each test FILE its own instance of this module —
+ * no cross-file bleed).
+ */
+import { vi } from 'vitest';
+import { createConnectionRegistry } from '@dimina-kit/electron-deck/main';
+/** Every WebContentsView ever constructed by the code under test, in
+ * construction order: attachNativeSimulator builds [0] = the native simulator
+ * content view, then attachNativeSimulatorDevtoolsHost builds [1] = the
+ * DevTools front-end host view. Reset in each file's beforeEach. */
+export const constructed = [];
+/** Service-host wcs registered by `makeServiceWc`, looked up by
+ * `electron.webContents.fromId` — mirrors real Electron's global wc registry
+ * so `onNativeServiceHostReady`'s `webContents.fromId(event.serviceWcId)`
+ * resolution has something real to find. */
+export const serviceWcRegistry = new Map();
+/** One stub wc surface shared by BOTH stub flavors (the constructed
+ * WebContentsView host wcs and the standalone service-host wcs) — a single
+ * factory instead of two hand-maintained near-identical literals. */
+function makeStubWc(id, overrides = {}) {
+    return {
+        destroyed: false,
+        id,
+        isDestroyed() { return this.destroyed; },
+        close: vi.fn(),
+        loadURL: vi.fn(() => Promise.resolve()),
+        loadFile: vi.fn(() => Promise.resolve()),
+        on: vi.fn(),
+        once: vi.fn(),
+        removeListener: vi.fn(),
+        setWindowOpenHandler: vi.fn(),
+        setZoomFactor: vi.fn(),
+        send: vi.fn(),
+        setMaxListeners: vi.fn(),
+        getMaxListeners: vi.fn(() => 10),
+        // DevTools front-end host wc surface (the WebContentsView flavor is used
+        // for `simulatorView.webContents`, i.e. the right-panel DevTools host).
+        isLoading: vi.fn(() => false),
+        executeJavaScript: vi.fn(() => Promise.resolve()),
+        setDevToolsWebContents: vi.fn(),
+        openDevTools: vi.fn(),
+        isDevToolsOpened: vi.fn(() => false),
+        closeDevTools: vi.fn(),
+        getURL: vi.fn(() => ''),
+        ...overrides,
+    };
+}
+/** The `electron` module surface view-manager and its injectors touch. */
+export function electronModuleMock() {
+    let nextId = 1;
+    class WebContentsView {
+        webContents;
+        setBounds = vi.fn();
+        setBackgroundColor = vi.fn();
+        constructor(_opts) {
+            this.webContents = makeStubWc(nextId++, {
+                close: vi.fn(function () { this.destroyed = true; }),
+            });
+            constructed.push(this);
+        }
+    }
+    const ipcMain = {
+        on: vi.fn(),
+        removeListener: vi.fn(),
+        handle: vi.fn(),
+        removeHandler: vi.fn(),
+    };
+    return {
+        WebContentsView,
+        ipcMain,
+        shell: { openExternal: vi.fn() },
+        nativeTheme: { shouldUseDarkColors: false, on: vi.fn(), removeListener: vi.fn() },
+        webContents: {
+            fromId: vi.fn((id) => serviceWcRegistry.get(id)),
+            getAllWebContents: vi.fn(() => []),
+        },
+        default: { ipcMain },
+    };
+}
+export function pathsModuleMock() {
+    return {
+        mainPreloadPath: '/stub/preload.js',
+        hostToolbarPreloadPath: '/stub/host-toolbar-preload.js',
+        cjsSiblingPreloadPath: (p) => p.replace(/\.js$/, '.cjs'),
+        devtoolsPackageRoot: '/stub/devtools-pkg-root',
+    };
+}
+export const SIM_URL = 'http://localhost:7788/simulator.html?appId=repoint';
+/** A hidden SERVICE-HOST BrowserWindow wc (top-level, can host DevTools). */
+export function makeServiceWc(id) {
+    const wc = makeStubWc(id, { isDevToolsOpened: vi.fn(() => true) });
+    serviceWcRegistry.set(id, wc);
+    return wc;
+}
+export function makeContext() {
+    const addChildView = vi.fn();
+    const removeChildView = vi.fn();
+    const contentView = { addChildView, removeChildView, children: [] };
+    const mainWindow = {
+        destroyed: false,
+        contentView,
+        isDestroyed() { return this.destroyed; },
+        getContentSize: () => [1280, 980],
+    };
+    const notify = {
+        popoverInit: vi.fn(),
+        popoverClosed: vi.fn(),
+        hostToolbarHeightChanged: vi.fn(),
+    };
+    // ── ctx.bridge stub ───────────────────────────────────────────────────────
+    // Minimal `BridgeRouterHandle`: `getServiceWc` resolves to whatever the test
+    // currently points `currentServiceWc` at (simulating a pre-warm-pool swap
+    // between render events), and `onRenderEvent` fans a manually-driven
+    // `RenderEvent` out to every subscriber (view-manager's own follow-path AND
+    // elements-forward's internal subscription both register here).
+    let currentServiceWc = null;
+    const renderEventListeners = new Set();
+    const serviceHostReadyListeners = new Set();
+    const bridge = {
+        isNativeHost: () => true,
+        resolveRenderWc: () => null,
+        getServiceWc: vi.fn(() => currentServiceWc),
+        getServiceWcForBridge: () => null,
+        getActiveRenderWc: () => null,
+        getActiveBridgeId: () => null,
+        onRenderEvent: (listener) => {
+            renderEventListeners.add(listener);
+            return () => renderEventListeners.delete(listener);
+        },
+        onServiceHostReady: (listener) => {
+            serviceHostReadyListeners.add(listener);
+            return () => serviceHostReadyListeners.delete(listener);
+        },
+        getDevice: () => null,
+        setDevice: () => { },
+        disposeSessionsForSimulator: () => Promise.resolve(),
+    };
+    function setActiveServiceWc(wc) {
+        currentServiceWc = wc;
+    }
+    function emitRenderEvent(event) {
+        for (const l of [...renderEventListeners])
+            l(event);
+    }
+    function emitServiceHostReady(event) {
+        for (const l of [...serviceHostReadyListeners])
+            l(event);
+    }
+    return {
+        addChildView,
+        removeChildView,
+        setActiveServiceWc,
+        emitRenderEvent,
+        emitServiceHostReady,
+        ctx: {
+            windows: {
+                mainWindow: mainWindow,
+            },
+            rendererDir: '/stub/renderer',
+            notify: notify,
+            connections: createConnectionRegistry(),
+            preloadPath: '/stub/sim-preload.js',
+            bridge: bridge,
+        },
+    };
+}
+//# sourceMappingURL=view-manager-devtools-host-test-fixtures.js.map

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

@@ -4,6 +4,7 @@ import type { BridgeRouterHandle } from '../ipc/bridge-router.js';
 import type { ConsoleForwarder } from './console-forward/index.js';
 import type { DiagnosticsBus } from './diagnostics/index.js';
 import type { NetworkForwarder } from './network-forward/index.js';
+import type { InternalDevtoolsWindow } from '../windows/internal-devtools-window/index.js';
 import { type CdpSessionBroker } from './cdp-session/index.js';
 import type { AppDataTap } from './simulator-appdata/index.js';
 import type { StorageApi } from './simulator-storage/index.js';
@@ -197,6 +198,15 @@ export interface WorkbenchContext {
      * DevTools host exist. Undefined until bootstrap wires it.
      */
     networkForward?: NetworkForwarder;
+    /**
+     * Controller for the standalone internal (app-wide) DevTools debug window
+     * — the independent floating CDP panel that debugs the whole Electron app
+     * (as opposed to the right-panel CDP, which inspects only the user's
+     * mini-program). Assembled in app bootstrap via
+     * `createInternalDevtoolsWindow(mainWindow)`; undefined only in contexts
+     * that skip that wiring (e.g. narrow test doubles).
+     */
+    internalDevtoolsWindow?: InternalDevtoolsWindow;
 }
 /**
  * Inputs for `createWorkbenchContext`. The scalar config fields it shares with

package/dist/main/utils/theme.d.ts

@@ -35,12 +35,16 @@ export declare function simDeskBg(): string;
  * The defect is platform-agnostic, so the fix is too: one `nativeTheme`
  * `updated` listener re-syncs every current and future BrowserWindow.
  *
- * Known limitation: on Linux the `updated` event does not fire for OS-level
- * system theme changes (electron/electron#25925) — only for explicit
- * `nativeTheme.themeSource` assignments. In-app theme switches go through
- * `applyTheme()` and are unaffected on every platform; the gap is limited to
- * Linux + `theme: 'system'` + an OS theme change, an upstream Electron
- * limitation that also leaves the renderer's `prefers-color-scheme` stale.
+ * Known limitation: on some Linux desktops (KDE Plasma + Wayland and other
+ * wlroots compositors) an OS-level system theme change flips `updated` with
+ * a stale/inverted `shouldUseDarkColors` instead of the correct value — a
+ * Chromium ≥142 regression (electron/electron#48736, crbug 462191707, open
+ * as of 2026-06) distinct from the older #25925 (fixed since Electron 13,
+ * 2021). GNOME/GTK-portal desktops are unaffected. In-app theme switches go
+ * through `applyTheme()` and are unaffected on every platform; the gap is
+ * limited to the affected Linux desktops + `theme: 'system'` + an OS theme
+ * change, an upstream Electron limitation that also leaves the renderer's
+ * `prefers-color-scheme` stale.
  *
  * Returns a Disposable that detaches the listener. Install it once during
  * app setup and hand the Disposable to the workbench registry.

package/dist/main/utils/theme.js

@@ -41,12 +41,16 @@ export function simDeskBg() {
  * The defect is platform-agnostic, so the fix is too: one `nativeTheme`
  * `updated` listener re-syncs every current and future BrowserWindow.
  *
- * Known limitation: on Linux the `updated` event does not fire for OS-level
- * system theme changes (electron/electron#25925) — only for explicit
- * `nativeTheme.themeSource` assignments. In-app theme switches go through
- * `applyTheme()` and are unaffected on every platform; the gap is limited to
- * Linux + `theme: 'system'` + an OS theme change, an upstream Electron
- * limitation that also leaves the renderer's `prefers-color-scheme` stale.
+ * Known limitation: on some Linux desktops (KDE Plasma + Wayland and other
+ * wlroots compositors) an OS-level system theme change flips `updated` with
+ * a stale/inverted `shouldUseDarkColors` instead of the correct value — a
+ * Chromium ≥142 regression (electron/electron#48736, crbug 462191707, open
+ * as of 2026-06) distinct from the older #25925 (fixed since Electron 13,
+ * 2021). GNOME/GTK-portal desktops are unaffected. In-app theme switches go
+ * through `applyTheme()` and are unaffected on every platform; the gap is
+ * limited to the affected Linux desktops + `theme: 'system'` + an OS theme
+ * change, an upstream Electron limitation that also leaves the renderer's
+ * `prefers-color-scheme` stale.
  *
  * Returns a Disposable that detaches the listener. Install it once during
  * app setup and hand the Disposable to the workbench registry.

package/dist/main/windows/internal-devtools-window/index.d.ts

@@ -0,0 +1,66 @@
+import type { WebContents } from 'electron';
+import { BrowserWindow } from 'electron';
+/**
+ * Standalone (non-dock) DevTools window for the whole Electron app — the
+ * independent floating CDP debug panel's host window. Unlike the right-panel
+ * CDP (`native-simulator-devtools-host.ts`, which re-points at a swappable
+ * service-host wc via a reconciler-driven overlay), `target` here is the main
+ * window's own webContents and never swaps, so this controller needs none of
+ * that machinery: just a plain window with a WebContentsView filling it as
+ * the DevTools front-end host.
+ *
+ * The window + its `setDevToolsWebContents` attachment are built ONCE (on
+ * the first `open()`) and never rebuilt afterward — the close button hides
+ * rather than destroys. This is deliberate, not an oversight: real-repro
+ * diagnostic instrumentation + a source-level Electron/Chromium
+ * investigation this session established that destroying and rebuilding
+ * this attachment on every close/reopen cycle cannot be made reliable.
+ * `closeDevTools()` is effectively a no-op on the `setDevToolsWebContents`
+ * external-front-end path (Electron's `InspectableWebContents::CloseDevTools`
+ * only does real cleanup when `managed_devtools_web_contents_` is set, which
+ * external attachments never populate) — the ONLY authoritative "detached"
+ * signal, `'devtools-closed'`, is tied to the OLD front-end host's underlying
+ * `content::WebContents` C++ object being destroyed, which was observed
+ * (real timestamped log, this session) to take 20+ seconds — the same
+ * order of magnitude as this app's own independently-discovered
+ * `'close'`-to-`'closed'` BrowserWindow teardown lag. This is a long-standing,
+ * unresolved upstream behavior (electron/electron#14095, #17168, #27110,
+ * #37356), not something fixable from this module. Electron's own
+ * `setDevToolsWebContents` documentation example builds its host window
+ * exactly once for the app's lifetime and never rebuilds it — reusing the
+ * same host sidesteps the entire bug class instead of chasing a fast
+ * "really detached now" signal that does not exist.
+ */
+export interface InternalDevtoolsWindowOptions {
+    /** Authority for "the app is quitting right now" (see app/lifecycle.ts).
+     * During a real quit every window is closing for real — the controller's
+     * habitual close-interception (preventDefault + hide) would CANCEL the
+     * quit and leave the process alive with a hidden window nothing will ever
+     * show again, so a truthy answer here lets the native close proceed. */
+    isAppQuitting?: () => boolean;
+}
+export interface InternalDevtoolsWindow {
+    /** Create (on the very first call) and show/focus the window, attaching
+     * its DevTools front-end host to `target`'s DevTools exactly once. Every
+     * later call just re-shows/focuses the SAME window and host — the
+     * underlying DevTools attachment is never rebuilt (see module doc). */
+    open(): void;
+    /** Actually destroy the window and release the DevTools attachment.
+     * Distinct from the user closing the window (which only hides it) — this
+     * is for real app-level teardown. Safe to call even if `open()` was never
+     * called. */
+    dispose(): void;
+    /** Subscribe to the front-end host's visibility: fires with the host wc
+     * when the window is built (first `open()`) or shown again, and with null
+     * when the window is hidden (user close) or destroyed (`dispose()`).
+     * Global CDP consumers (network-forward, service-console) gate their
+     * dispatch target here — hidden means "stop spending work mirroring into
+     * a window nobody can see," not "the attachment is gone." A subscriber
+     * registering while the window is ALREADY visible gets the current host
+     * replayed one microtask later (same catch-up contract as bridge-router's
+     * `onServiceHostReady`) — consumers wired up after `open()` must not stay
+     * stuck believing there is no host. Returns an unsubscribe. */
+    onHostChanged(handler: (hostWc: WebContents | null) => void): () => void;
+}
+export declare function createInternalDevtoolsWindow(target: BrowserWindow, opts?: InternalDevtoolsWindowOptions): InternalDevtoolsWindow;
+//# sourceMappingURL=index.d.ts.map