@dimina-kit/devtools 0.4.0 → 0.5.0-dev.20260908120530

package/dist/main/utils/ipc-registry.js

@@ -1,5 +1,5 @@
 import { ipcMain } from 'electron';
-import { DisposableRegistry } from '@dimina-kit/electron-deck/main';
+import { addMuxedInvokeHandler, isMainFrameIpcSender, } from '@dimina-kit/electron-deck/main';
 import { IpcValidationError } from './ipc-schema.js';
 import { createLogger } from './logger.js';
 const log = createLogger('ipc');
@@ -30,97 +30,154 @@ function summarizeSender(sender) {
     const url = sender.getURL();
     return `id=${sender.id} ${url.slice(0, 120)}`;
 }
-function isMainFrameSender(event) {
-    // Read via loose casts: the Electron types declare these always-present, but
-    // unit-test stubs legitimately omit them — and real events can carry a null
-    // senderFrame after navigation/destruction.
-    const frame = event.senderFrame;
-    const main = event.sender.mainFrame;
-    // Frame-unaware stub (NEITHER field modeled) → not a real frame boundary; the
-    // sender-id white-list is the gate. Real events always have both, so they fall
-    // through to the strict check; a partial/malformed event (only one field) also
-    // falls through and fail-closes below rather than escaping here.
-    if (frame === undefined && main === undefined)
-        return true;
-    // Real event, unresolvable frame (navigate-after-send / destroyed) → reject.
-    if (frame == null || main == null)
-        return false;
-    return frame.routingId === main.routingId && frame.processId === main.processId;
-}
+/**
+ * Defense-in-depth frame check (sits alongside the sender white-list). A trusted
+ * webContents could embed a sub-frame of arbitrary origin; only its top (main)
+ * frame should reach gated IPC, so a sub-frame can't spoof the trusted sender.
+ *
+ * Verified on Electron 41 that `event.senderFrame` is reliably present on
+ * invoke / send / sendSync — including the editor's `beforeunload` sendSync
+ * write — and equals `sender.mainFrame` for top-frame traffic, so this never
+ * mis-rejects legitimate callers.
+ *
+ * Fail-closed on a null frame for REAL events: a sub-frame can send a message
+ * and immediately navigate/destroy itself, so by delivery time `senderFrame`
+ * resolves to null — allowing that would let the navigate-after-send trick
+ * bypass the boundary. A real Electron event always exposes the `senderFrame`
+ * property and `sender.mainFrame`, so we can tell a real event (frame-modeled,
+ * possibly null) from a frame-unaware unit-test stub (neither present) and only
+ * skip the check for the latter (the sender-id white-list still gates tests).
+ */
+/** Internal marker for "this sender is not allowed on this channel". */
+const REJECT = Symbol('ipc-reject');
+// Channel multiplexing (one real `ipcMain.handle` per channel, dispatched to
+// whichever per-window registration claims the sender — needed because the
+// storage, WXML and AppData panels each register their channels once per
+// window) is shared with dimina-electron-runtime's bridge router; see
+// @dimina-kit/electron-deck/main's ipc-mux.ts for the mux itself.
 /**
  * Tiny fluent helper that wraps every `ipcMain.handle` / `ipcMain.on` with a
  * matching removeHandler/removeListener registered into an internal registry.
  *
- * Each `register*Ipc(ctx)` returns one of these as a Disposable so the
+ * Each `register*Ipc(...)` returns one of these as a Disposable so the
  * workbench-level registry can dispose all built-in handlers in one shot.
  *
- * If a {@link SenderPolicy} is provided, every incoming invocation is gated:
- * - `handle`: rejected senders cause the invoke promise to reject with
- *   `Error('IPC sender rejected for channel <channel>')`.
- * - `on`: rejected senders are silently dropped (the original listener is
- *   never called).
- * In both cases a single `console.warn` is emitted with the channel name
- * and a short sender summary. Without a policy the wrapper is a no-op,
- * preserving backwards compatibility for unit tests and callers that
- * opted out.
+ * The constructor takes either a {@link SenderPolicy} (trust only: is this
+ * sender allowed?) or an {@link IpcContextSource} (trust plus ownership: which
+ * window context does this sender belong to?). With either, every incoming
+ * invocation is gated:
+ * - `handle` / `handleRouted`: rejected senders cause the invoke promise to
+ *   reject with `Error('IPC sender rejected for channel <channel>')`.
+ * - `on` / `onRouted`: rejected senders are silently dropped (the original
+ *   listener is never called).
+ * - `handleSync` / `handleSyncRouted`: rejected senders get a structured
+ *   `{ ok: false, code: 'EREJECTED', … }` returnValue, because sendSync blocks
+ *   the renderer until one is set.
+ * In every case a single `console.warn` is emitted with the channel name and a
+ * short sender summary. With no policy — or a source that declares itself
+ * `ungated` — the wrapper is a pass-through, preserving backwards
+ * compatibility for unit tests and callers that opted out.
+ *
+ * The `*Routed` variants hand the owning context to the handler as its first
+ * argument. `TCtx` is `never` unless the registry was built from a source, so
+ * they are unusable (and unreachable) on a policy-only registry.
  */
 export class IpcRegistry {
+    // Every cleanup is a synchronous ipcMain.removeHandler/removeListener call,
+    // so dispose() can (and must) run them all before returning: callers
+    // `dispose()` without awaiting and rely on every channel being unregistered
+    // synchronously — an async registry would leave all but the first handler
+    // live until a later microtask.
+    cleanups = [];
+    _disposed = false;
     policy;
-    registry = new DisposableRegistry();
-    constructor(policy) {
-        this.policy = policy;
+    source;
+    /** False reproduces the policy-less pass-through exactly: no main-frame
+     * check, and a synchronous handler keeps its synchronous return value. */
+    gated;
+    constructor(policyOrSource) {
+        const isPolicy = typeof policyOrSource === 'function';
+        this.policy = isPolicy ? policyOrSource : null;
+        this.source = policyOrSource != null && !isPolicy ? policyOrSource : null;
+        this.gated = this.policy != null || (this.source != null && !this.source.ungated);
     }
-    handle(channel, fn) {
-        const policy = this.policy;
+    /** Trust gate and owner resolution for one incoming message. */
+    admit(event) {
+        const source = this.source;
+        if (source) {
+            // An ungated source always claims the sender, so the frame check — part
+            // of the trust gate, not of ownership — stays off with it.
+            if (source.ungated)
+                return source.resolve(event.sender);
+            if (!isMainFrameIpcSender(event))
+                return REJECT;
+            const ctx = source.resolve(event.sender);
+            return ctx == null ? REJECT : ctx;
+        }
+        // A bare policy answers trust only, so the accepted branch carries no
+        // context; `TCtx` is `never` in that mode, so no handler can observe it.
+        if (!this.policy)
+            return undefined;
+        return this.policy(event.sender) && isMainFrameIpcSender(event)
+            ? undefined
+            : REJECT;
+    }
+    warnRejected(channel, sender) {
+        console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+    }
+    addInvokeHandler(channel, invoke) {
         // The gate is `async` so a rejected sender surfaces as a *rejected
         // promise* (the invoke-result contract) rather than a synchronous throw —
         // synchronous throws can escape callers that wrap the result in
         // `Promise.resolve(...)` instead of `await`-ing it directly.
-        const guarded = policy
+        const guarded = this.gated
             ? async (event, ...args) => {
-                const sender = event.sender;
-                if (!policy(sender) || !isMainFrameSender(event)) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
                     throw new Error(`IPC sender rejected for channel ${channel}`);
                 }
-                return fn(event, ...args);
+                return invoke(ctx, event, args);
             }
-            : fn;
-        ipcMain.handle(channel, guarded);
-        this.registry.add(() => ipcMain.removeHandler(channel));
+            : (event, ...args) => invoke(this.admit(event), event, args);
+        this.cleanups.push(addMuxedInvokeHandler(ipcMain, channel, {
+            claims: (event) => this.admit(event) !== REJECT,
+            handle: guarded,
+        }));
         return this;
     }
-    /**
-     * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
-     * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
-     * so `fn` MUST be synchronous and return the value to hand back. The sender
-     * policy gates it like {@link handle}; a rejected sender or a thrown error
-     * yields a structured `{ ok: false, code, message }` returnValue instead of
-     * the silent drop `on` uses, so the blocked renderer always gets an answer.
-     */
-    handleSync(channel, fn) {
-        const policy = this.policy;
+    handle(channel, fn) {
+        const raw = fn;
+        return this.addInvokeHandler(channel, (_ctx, event, args) => raw(event, ...args));
+    }
+    /** {@link handle} answered by the context that owns the calling sender. */
+    handleRouted(channel, fn) {
+        return this.addInvokeHandler(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
+    addSyncHandler(channel, invoke) {
         const listener = (event, ...args) => {
-            // Everything — including the policy check — runs inside the try so EVERY
-            // path sets `event.returnValue`. sendSync blocks the renderer until it is
+            const syncEvent = event;
+            // Everything — including the gate — runs inside the try so EVERY path
+            // sets `event.returnValue`. sendSync blocks the renderer until it is
             // set, so an unset value (e.g. a throwing policy fn) would hang the
             // renderer forever; the catch guarantees a sentinel instead.
             try {
-                if (policy && (!policy(event.sender) || !isMainFrameSender(event))) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(event.sender)})`);
-                    event.returnValue = {
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
+                    syncEvent.returnValue = {
                         ok: false,
                         code: 'EREJECTED',
                         message: `IPC sender rejected for channel ${channel}`,
                     };
                     return;
                 }
-                event.returnValue = fn(event, ...args);
+                syncEvent.returnValue = invoke(ctx, event, args);
             }
             catch (err) {
                 reportListenerError(channel, err);
                 const code = err?.code;
-                event.returnValue = {
+                syncEvent.returnValue = {
                     ok: false,
                     code: typeof code === 'string' ? code : 'EUNKNOWN',
                     message: err instanceof Error ? err.message : String(err),
@@ -128,17 +185,25 @@ export class IpcRegistry {
             }
         };
         ipcMain.on(channel, listener);
-        this.registry.add(() => {
-            ipcMain.removeListener(channel, listener);
-        });
+        this.cleanups.push(() => ipcMain.removeListener(channel, listener));
         return this;
     }
-    on(channel, fn) {
-        const policy = this.policy;
-        const raw = fn;
-        const safeInvoke = (event, args) => {
+    /**
+     * Register a SYNCHRONOUS `ipcRenderer.sendSync` handler. Unlike {@link on}
+     * (fire-and-forget), the renderer is blocked until we set `event.returnValue`,
+     * so `fn` MUST be synchronous and return the value to hand back.
+     */
+    handleSync(channel, fn) {
+        return this.addSyncHandler(channel, (_ctx, event, args) => fn(event, ...args));
+    }
+    /** {@link handleSync} answered by the context that owns the calling sender. */
+    handleSyncRouted(channel, fn) {
+        return this.addSyncHandler(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
+    addListener(channel, invoke) {
+        const safeInvoke = (ctx, event, args) => {
             try {
-                const ret = raw(event, ...args);
+                const ret = invoke(ctx, event, args);
                 if (isThenable(ret)) {
                     // Async listeners would otherwise leak rejections into Electron's
                     // event loop as `UnhandledPromiseRejection`. Funnel them into the
@@ -150,24 +215,49 @@ export class IpcRegistry {
                 reportListenerError(channel, err);
             }
         };
-        const guarded = policy
+        const guarded = this.gated
             ? (event, ...args) => {
-                const sender = event.sender;
-                if (!policy(sender) || !isMainFrameSender(event)) {
-                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                const ctx = this.admit(event);
+                if (ctx === REJECT) {
+                    this.warnRejected(channel, event.sender);
                     return;
                 }
-                safeInvoke(event, args);
+                safeInvoke(ctx, event, args);
             }
-            : (event, ...args) => safeInvoke(event, args);
+            : (event, ...args) => safeInvoke(this.admit(event), event, args);
         ipcMain.on(channel, guarded);
-        this.registry.add(() => {
-            ipcMain.removeListener(channel, guarded);
-        });
+        this.cleanups.push(() => ipcMain.removeListener(channel, guarded));
         return this;
     }
+    on(channel, fn) {
+        const raw = fn;
+        return this.addListener(channel, (_ctx, event, args) => raw(event, ...args));
+    }
+    /** {@link on} answered by the context that owns the calling sender. */
+    onRouted(channel, fn) {
+        return this.addListener(channel, (ctx, event, args) => fn(ctx, event, ...args));
+    }
     dispose() {
-        return this.registry.dispose();
+        // Synchronous drain (LIFO, idempotent): every channel is unregistered
+        // before this returns; the promise only carries aggregated errors.
+        if (this._disposed)
+            return Promise.resolve();
+        this._disposed = true;
+        const items = this.cleanups.slice().reverse();
+        this.cleanups = [];
+        const errors = [];
+        for (const cleanup of items) {
+            try {
+                cleanup();
+            }
+            catch (e) {
+                errors.push(e);
+            }
+        }
+        if (errors.length > 0) {
+            return Promise.reject(new AggregateError(errors, 'IpcRegistry encountered errors during dispose'));
+        }
+        return Promise.resolve();
     }
 }
 //# sourceMappingURL=ipc-registry.js.map

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

@@ -31,7 +31,25 @@ export declare const mainPreloadPath: string;
  * npm/pnpm node_modules and ASAR packaging alike get an absolute, correct path.
  */
 export declare const hostToolbarRuntimePreloadPath: string;
+/** Session-registered sidebar-runtime preload bundle, mirroring {@link hostToolbarRuntimePreloadPath}. */
+export declare const hostSidebarRuntimePreloadPath: string;
+/** Session-registered dialog-runtime preload bundle, mirroring {@link hostToolbarRuntimePreloadPath}. */
+export declare const hostDialogRuntimePreloadPath: string;
 export declare const simulatorDir: string;
+/**
+ * DevTools builds its own copy of every native mini-app runtime asset. Pin the
+ * shared runtime bridge to that copy so a packaged client never depends on the
+ * standalone npm package's optional asset assembly step.
+ */
+export declare const runtimeAssetPaths: {
+    root: string;
+    simulatorDir: string;
+    simulatorPreloadPath: string;
+    renderHostHtmlPath: string;
+    renderHostPreloadPath: string;
+    serviceHostHtmlPath: string;
+    serviceHostPreloadPath: string;
+};
 export declare function getRendererDir(): string;
 export declare function getPreloadDir(): string;
 export declare function getRendererHtml(filename: string): string;

package/dist/main/utils/paths.js

@@ -59,7 +59,25 @@ export const mainPreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/wind
  * npm/pnpm node_modules and ASAR packaging alike get an absolute, correct path.
  */
 export const hostToolbarRuntimePreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/host-toolbar-runtime.cjs');
+/** Session-registered sidebar-runtime preload bundle, mirroring {@link hostToolbarRuntimePreloadPath}. */
+export const hostSidebarRuntimePreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/host-sidebar-runtime.cjs');
+/** Session-registered dialog-runtime preload bundle, mirroring {@link hostToolbarRuntimePreloadPath}. */
+export const hostDialogRuntimePreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/host-dialog-runtime.cjs');
 export const simulatorDir = path.join(devtoolsPackageRoot, 'dist/simulator');
+/**
+ * DevTools builds its own copy of every native mini-app runtime asset. Pin the
+ * shared runtime bridge to that copy so a packaged client never depends on the
+ * standalone npm package's optional asset assembly step.
+ */
+export const runtimeAssetPaths = {
+    root: path.join(devtoolsPackageRoot, 'dist'),
+    simulatorDir,
+    simulatorPreloadPath: path.join(devtoolsPackageRoot, 'dist/preload/windows/simulator.cjs'),
+    renderHostHtmlPath: path.join(devtoolsPackageRoot, 'dist/render-host/pageFrame.html'),
+    renderHostPreloadPath: path.join(devtoolsPackageRoot, 'dist/render-host/preload.cjs'),
+    serviceHostHtmlPath: path.join(devtoolsPackageRoot, 'dist/service-host/service.html'),
+    serviceHostPreloadPath: path.join(devtoolsPackageRoot, 'dist/service-host/preload.cjs'),
+};
 export function getRendererDir() {
     return rendererDir;
 }

package/dist/main/utils/sender-policy.d.ts

@@ -8,7 +8,7 @@ import type { SenderPolicy } from './ipc-registry.js';
  * - the main window's renderer
  * - the optional workbench settings BrowserWindow's renderer (when open)
  * - the settings overlay view (when open)
- * - the popover overlay view (when open)
+ * - the popover and tooltip overlay views (when open)
  *
  * The simulator webview is intentionally NOT on this list. Anything it
  * needs from main (currently just the custom-apis bridge — see
@@ -31,4 +31,13 @@ import type { SenderPolicy } from './ipc-registry.js';
  * iframe — is rejected.
  */
 export declare function createWorkbenchSenderPolicy(ctx: Pick<WorkbenchContext, 'windows' | 'views' | 'trustedWindowSenderIds'>): SenderPolicy;
+/**
+ * The senders this context structurally OWNS: its own main-window renderer,
+ * its own settings window and the overlay views mounted inside it. Deliberately
+ * excludes `trustedWindowSenderIds` — that map is shared by the whole app, so
+ * every context would claim the same host window and ownership would stop being
+ * unique. `createWindowContextRouter` routes on this check first for exactly
+ * that reason.
+ */
+export declare function createWorkbenchOwnedSenderCheck(ctx: Pick<WorkbenchContext, 'windows' | 'views'>): SenderPolicy;
 //# sourceMappingURL=sender-policy.d.ts.map

package/dist/main/utils/sender-policy.js

@@ -6,7 +6,7 @@
  * - the main window's renderer
  * - the optional workbench settings BrowserWindow's renderer (when open)
  * - the settings overlay view (when open)
- * - the popover overlay view (when open)
+ * - the popover and tooltip overlay views (when open)
  *
  * The simulator webview is intentionally NOT on this list. Anything it
  * needs from main (currently just the custom-apis bridge — see
@@ -29,6 +29,26 @@
  * iframe — is rejected.
  */
 export function createWorkbenchSenderPolicy(ctx) {
+    const ownsSender = createWorkbenchOwnedSenderCheck(ctx);
+    return (sender) => {
+        if (ownsSender(sender))
+            return true;
+        if (sender.isDestroyed())
+            return false;
+        // Host-registered trusted windows (registerTrustedWindow). The map is
+        // app-wide, so this is the one accepted sender no single context owns.
+        return ctx.trustedWindowSenderIds.has(sender.id);
+    };
+}
+/**
+ * The senders this context structurally OWNS: its own main-window renderer,
+ * its own settings window and the overlay views mounted inside it. Deliberately
+ * excludes `trustedWindowSenderIds` — that map is shared by the whole app, so
+ * every context would claim the same host window and ownership would stop being
+ * unique. `createWindowContextRouter` routes on this check first for exactly
+ * that reason.
+ */
+export function createWorkbenchOwnedSenderCheck(ctx) {
     return (sender) => {
         if (sender.isDestroyed())
             return false;
@@ -38,9 +58,6 @@ export function createWorkbenchSenderPolicy(ctx) {
         // Standalone settings BrowserWindow renderer
         if (ctx.windows.isSettingsWindowSender(sender.id))
             return true;
-        // Host-registered trusted windows (registerTrustedWindow)
-        if (ctx.trustedWindowSenderIds.has(sender.id))
-            return true;
         // Settings overlay view (mounted inside the main window)
         const settingsViewId = ctx.views.getSettingsWebContentsId();
         if (settingsViewId != null && sender.id === settingsViewId)
@@ -49,6 +66,27 @@ export function createWorkbenchSenderPolicy(ctx) {
         const popoverViewId = ctx.views.getPopoverWebContentsId();
         if (popoverViewId != null && sender.id === popoverViewId)
             return true;
+        // Tooltip overlay view. It loads only the bundled local renderer and needs
+        // the shared overlay-ready + intrinsic-measurement channels.
+        const tooltipViewId = ctx.views.getTooltipWebContentsId();
+        if (tooltipViewId != null && sender.id === tooltipViewId)
+            return true;
+        // Project-create-dialog overlay view. Devtools-owned bundled renderer
+        // (the WCV that replaced the Radix DOM-portal dialog), same trust level
+        // as settings/popover/tooltip.
+        const projectCreateDialogViewId = ctx.views.getProjectCreateDialogWebContentsId();
+        if (projectCreateDialogViewId != null && sender.id === projectCreateDialogViewId)
+            return true;
+        // Update-available overlay view. Same devtools-owned trust level.
+        const updateDialogViewId = ctx.views.getUpdateDialogWebContentsId();
+        if (updateDialogViewId != null && sender.id === updateDialogViewId)
+            return true;
+        // Device-picker overlay view. Same devtools-owned trust level — the
+        // simulator toolbar's device selector, moved out of the main renderer's
+        // DOM so the simulator WCV can't occlude it.
+        const devicePickerViewId = ctx.views.getDevicePickerWebContentsId();
+        if (devicePickerViewId != null && sender.id === devicePickerViewId)
+            return true;
         // The host-toolbar overlay is DELIBERATELY NOT trusted here. The host loads
         // arbitrary content into it, so granting it the global white-list would open
         // all ~72 IpcRegistry channels to that content. Its one channel (the reverse

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

@@ -14,8 +14,14 @@ export declare function themeBg(): string;
  * the desk is a neutral grey kept a touch off the window so the light-colored
  * phone keeps contrast against it in BOTH schemes.
  *
- * Dark:  hsl(0 0% 7%)  ≈ #121212  (the long-standing desk color — unchanged)
- * Light: hsl(0 0% 91%) ≈ #e8e8e8  (neutral grey; the white phone reads on it)
+ * Dark: #282828 | Light: #f7f7f9 — both match the renderer's --color-surface-2
+ * chrome tone (@dimina-kit/design, css/tokens.css). Dark is a package-owned
+ * value rather than a Cornetto --qd-muted alias: pixel-verified against Figma
+ * node 66:1729 at rgb(40,40,40),
+ * which doesn't match any Cornetto dark token (--qd-muted is #383838, off by
+ * 16 units — confirmed too light against the app's own dark-mode screenshots).
+ * Light's #f7f7f9 IS an exact --qd-muted match (verified against node 25:5),
+ * so only dark diverges from the Cornetto alias.
  *
  * MUST stay equal to the renderer's `--color-sim-bg` (design.css) and the
  * simulator page's `.device-shell-root` background (device-shell.css): the WCV,
@@ -35,12 +41,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

@@ -18,8 +18,14 @@ export function themeBg() {
  * the desk is a neutral grey kept a touch off the window so the light-colored
  * phone keeps contrast against it in BOTH schemes.
  *
- * Dark:  hsl(0 0% 7%)  ≈ #121212  (the long-standing desk color — unchanged)
- * Light: hsl(0 0% 91%) ≈ #e8e8e8  (neutral grey; the white phone reads on it)
+ * Dark: #282828 | Light: #f7f7f9 — both match the renderer's --color-surface-2
+ * chrome tone (@dimina-kit/design, css/tokens.css). Dark is a package-owned
+ * value rather than a Cornetto --qd-muted alias: pixel-verified against Figma
+ * node 66:1729 at rgb(40,40,40),
+ * which doesn't match any Cornetto dark token (--qd-muted is #383838, off by
+ * 16 units — confirmed too light against the app's own dark-mode screenshots).
+ * Light's #f7f7f9 IS an exact --qd-muted match (verified against node 25:5),
+ * so only dark diverges from the Cornetto alias.
  *
  * MUST stay equal to the renderer's `--color-sim-bg` (design.css) and the
  * simulator page's `.device-shell-root` background (device-shell.css): the WCV,
@@ -27,7 +33,7 @@ export function themeBg() {
  * never flashes a mismatched strip. Update all three together.
  */
 export function simDeskBg() {
-    return nativeTheme.shouldUseDarkColors ? '#121212' : '#e8e8e8';
+    return nativeTheme.shouldUseDarkColors ? '#282828' : '#f7f7f9';
 }
 /**
  * Install a single process-wide listener that keeps every window's native
@@ -41,12 +47,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