@dimina-kit/devtools 0.3.1 → 0.3.2-dev.20260522085907

package/dist/main/utils/ipc-registry.d.ts

@@ -0,0 +1,39 @@
+import type { WebContents } from 'electron';
+import { ipcMain } from 'electron';
+import { type Disposable } from './disposable.js';
+type HandleFn = Parameters<typeof ipcMain.handle>[1];
+type ListenerFn = Parameters<typeof ipcMain.on>[1];
+/**
+ * Trust predicate used to gate IPC delivery on the main process.
+ *
+ * Returns true when the calling WebContents is allowed to invoke / emit on
+ * the channel, false otherwise.
+ */
+export type SenderPolicy = (sender: WebContents) => boolean;
+/**
+ * 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
+ * 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.
+ */
+export declare class IpcRegistry implements Disposable {
+    private policy?;
+    private registry;
+    constructor(policy?: SenderPolicy | undefined);
+    handle(channel: string, fn: HandleFn): this;
+    on(channel: string, fn: ListenerFn): this;
+    dispose(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=ipc-registry.d.ts.map

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

@@ -0,0 +1,109 @@
+import { ipcMain } from 'electron';
+import { DisposableRegistry } from './disposable.js';
+import { IpcValidationError } from './ipc-schema.js';
+import { createLogger } from './logger.js';
+const log = createLogger('ipc');
+/**
+ * Funnels errors thrown by an `on()` listener into the logger so they don't
+ * escape into Electron's event loop. Validation errors get a compact `warn`
+ * (channel + zod paths), other errors get a full `error` with stack.
+ */
+function reportListenerError(channel, err) {
+    if (err instanceof IpcValidationError) {
+        log.warn(`schema reject on '${channel}' at [${err.paths.join(', ')}]`);
+        return;
+    }
+    if (err instanceof Error) {
+        log.error(`listener threw on '${channel}': ${err.message}`, err.stack);
+        return;
+    }
+    log.error(`listener threw on '${channel}'`, err);
+}
+function isThenable(v) {
+    return (v != null &&
+        (typeof v === 'object' || typeof v === 'function') &&
+        typeof v.then === 'function');
+}
+function summarizeSender(sender) {
+    if (sender.isDestroyed())
+        return '<destroyed>';
+    const url = sender.getURL();
+    return `id=${sender.id} ${url.slice(0, 120)}`;
+}
+/**
+ * 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
+ * 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.
+ */
+export class IpcRegistry {
+    policy;
+    registry = new DisposableRegistry();
+    constructor(policy) {
+        this.policy = policy;
+    }
+    handle(channel, fn) {
+        const policy = this.policy;
+        const guarded = policy
+            ? (event, ...args) => {
+                const sender = event.sender;
+                if (!policy(sender)) {
+                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                    throw new Error(`IPC sender rejected for channel ${channel}`);
+                }
+                return fn(event, ...args);
+            }
+            : fn;
+        ipcMain.handle(channel, guarded);
+        this.registry.add(() => ipcMain.removeHandler(channel));
+        return this;
+    }
+    on(channel, fn) {
+        const policy = this.policy;
+        const raw = fn;
+        const safeInvoke = (event, args) => {
+            try {
+                const ret = raw(event, ...args);
+                if (isThenable(ret)) {
+                    // Async listeners would otherwise leak rejections into Electron's
+                    // event loop as `UnhandledPromiseRejection`. Funnel them into the
+                    // same logger path as sync throws.
+                    Promise.resolve(ret).catch((err) => reportListenerError(channel, err));
+                }
+            }
+            catch (err) {
+                reportListenerError(channel, err);
+            }
+        };
+        const guarded = policy
+            ? (event, ...args) => {
+                const sender = event.sender;
+                if (!policy(sender)) {
+                    console.warn(`[ipc] sender rejected for channel '${channel}' (${summarizeSender(sender)})`);
+                    return;
+                }
+                safeInvoke(event, args);
+            }
+            : (event, ...args) => safeInvoke(event, args);
+        ipcMain.on(channel, guarded);
+        this.registry.add(() => {
+            ipcMain.removeListener(channel, guarded);
+        });
+        return this;
+    }
+    dispose() {
+        return this.registry.dispose();
+    }
+}
+//# sourceMappingURL=ipc-registry.js.map

package/dist/main/utils/ipc-schema.d.ts

@@ -0,0 +1,28 @@
+import type { z } from 'zod';
+/**
+ * Thrown by {@link validate} when an IPC payload fails its zod schema.
+ *
+ * Carries the channel name plus a compact list of failing zod paths so
+ * the IpcRegistry wrapper can log a short, actionable summary without
+ * dumping the full payload.
+ */
+export declare class IpcValidationError extends Error {
+    readonly channel: string;
+    readonly paths: string[];
+    constructor(channel: string, issues: ReadonlyArray<{
+        path: ReadonlyArray<PropertyKey>;
+    }>);
+}
+/**
+ * Parse an IPC handler's argument tuple against a zod schema.
+ *
+ * On failure: warns to console with the channel name + issue list, then throws
+ * an {@link IpcValidationError} so that:
+ *  - `ipcMain.handle` invocations reject the renderer's invoke promise
+ *    without leaking schema internals.
+ *  - `ipcMain.on` listeners (wrapped by IpcRegistry.on) can recognise the
+ *    error type and log a structured warning instead of letting the throw
+ *    escape into Electron's event loop.
+ */
+export declare function validate<T extends z.ZodTypeAny>(channel: string, schema: T, args: unknown[]): z.infer<T>;
+//# sourceMappingURL=ipc-schema.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * Thrown by {@link validate} when an IPC payload fails its zod schema.
+ *
+ * Carries the channel name plus a compact list of failing zod paths so
+ * the IpcRegistry wrapper can log a short, actionable summary without
+ * dumping the full payload.
+ */
+export class IpcValidationError extends Error {
+    channel;
+    paths;
+    constructor(channel, issues) {
+        const paths = issues.map((i) => i.path.map((p) => String(p)).join('.') || '<root>');
+        super(`Invalid IPC arguments for ${channel}`);
+        this.name = 'IpcValidationError';
+        this.channel = channel;
+        this.paths = paths;
+    }
+}
+/**
+ * Parse an IPC handler's argument tuple against a zod schema.
+ *
+ * On failure: warns to console with the channel name + issue list, then throws
+ * an {@link IpcValidationError} so that:
+ *  - `ipcMain.handle` invocations reject the renderer's invoke promise
+ *    without leaking schema internals.
+ *  - `ipcMain.on` listeners (wrapped by IpcRegistry.on) can recognise the
+ *    error type and log a structured warning instead of letting the throw
+ *    escape into Electron's event loop.
+ */
+export function validate(channel, schema, args) {
+    const r = schema.safeParse(args);
+    if (!r.success) {
+        console.warn('[ipc] schema reject', channel, r.error.issues);
+        throw new IpcValidationError(channel, r.error.issues);
+    }
+    return r.data;
+}
+//# sourceMappingURL=ipc-schema.js.map

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

@@ -1,6 +1,12 @@
 export declare const devtoolsPackageRoot: string;
 export declare const rendererDir: string;
 export declare const defaultPreloadPath: string;
+/**
+ * Preload bundle for the main window, settings window, and the settings /
+ * popover overlay WebContentsViews. Exposes `window.devtools.ipc` via
+ * contextBridge so the renderer never needs `window.require('electron')`.
+ */
+export declare const mainPreloadPath: string;
 export declare const simulatorDir: string;
 export declare function getRendererDir(): string;
 export declare function getPreloadDir(): string;

package/dist/main/utils/paths.js

@@ -25,6 +25,12 @@ function resolveDevtoolsPackageRoot() {
 export const devtoolsPackageRoot = resolveDevtoolsPackageRoot();
 export const rendererDir = path.join(devtoolsPackageRoot, 'dist/renderer');
 export const defaultPreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/simulator.js');
+/**
+ * Preload bundle for the main window, settings window, and the settings /
+ * popover overlay WebContentsViews. Exposes `window.devtools.ipc` via
+ * contextBridge so the renderer never needs `window.require('electron')`.
+ */
+export const mainPreloadPath = path.join(devtoolsPackageRoot, 'dist/preload/windows/main.cjs');
 export const simulatorDir = path.join(devtoolsPackageRoot, 'dist/simulator');
 export function getRendererDir() {
     return rendererDir;

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

@@ -0,0 +1,25 @@
+import type { WorkbenchContext } from '../services/workbench-context.js';
+import type { SenderPolicy } from './ipc-registry.js';
+/**
+ * Default workbench sender white-list.
+ *
+ * An IPC message is accepted only when its `event.sender` matches one of
+ * the WebContents the main process itself created and trusts:
+ * - 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 simulator webview is intentionally NOT on this list. Anything it
+ * needs from main (currently just the custom-apis bridge — see
+ * `installCustomApisBridge` in `src/preload/runtime/custom-apis.ts` and the
+ * matching `useCustomApiProxy` host hook) proxies through the trusted
+ * main-window renderer via `ipcRenderer.sendToHost` + `<webview>.send`.
+ * Keeping the guest off this list contains the blast radius if the
+ * simulator content is ever compromised.
+ *
+ * Any other sender — including a stale/destroyed sender or an unknown
+ * iframe — is rejected.
+ */
+export declare function createWorkbenchSenderPolicy(ctx: Pick<WorkbenchContext, 'windows' | 'views'>): SenderPolicy;
+//# sourceMappingURL=sender-policy.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * Default workbench sender white-list.
+ *
+ * An IPC message is accepted only when its `event.sender` matches one of
+ * the WebContents the main process itself created and trusts:
+ * - 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 simulator webview is intentionally NOT on this list. Anything it
+ * needs from main (currently just the custom-apis bridge — see
+ * `installCustomApisBridge` in `src/preload/runtime/custom-apis.ts` and the
+ * matching `useCustomApiProxy` host hook) proxies through the trusted
+ * main-window renderer via `ipcRenderer.sendToHost` + `<webview>.send`.
+ * Keeping the guest off this list contains the blast radius if the
+ * simulator content is ever compromised.
+ *
+ * Any other sender — including a stale/destroyed sender or an unknown
+ * iframe — is rejected.
+ */
+export function createWorkbenchSenderPolicy(ctx) {
+    return (sender) => {
+        if (sender.isDestroyed())
+            return false;
+        // Main window renderer
+        if (ctx.windows.isMainSender(sender.id))
+            return true;
+        // Standalone settings BrowserWindow renderer
+        if (ctx.windows.isSettingsWindowSender(sender.id))
+            return true;
+        // Settings overlay view (mounted inside the main window)
+        const settingsViewId = ctx.views.getSettingsWebContentsId();
+        if (settingsViewId != null && sender.id === settingsViewId)
+            return true;
+        // Popover overlay view
+        const popoverViewId = ctx.views.getPopoverWebContentsId();
+        if (popoverViewId != null && sender.id === popoverViewId)
+            return true;
+        // simulator <webview> proxies through main-window renderer (see file header).
+        return false;
+    };
+}
+//# sourceMappingURL=sender-policy.js.map

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

@@ -1,3 +1,4 @@
+import { type Disposable } from './disposable.js';
 /**
  * Background color that matches the current system color scheme.
  * Pass as `backgroundColor` when creating BrowserWindows to prevent
@@ -7,4 +8,27 @@
  * Light: hsl(0 0% 98%) ≈ #fafafa  (--color-bg)
  */
 export declare function themeBg(): string;
+/**
+ * Install a single process-wide listener that keeps every window's native
+ * `backgroundColor` in sync with the active color scheme.
+ *
+ * A window's `backgroundColor` is otherwise frozen at the value passed to its
+ * constructor: after a theme switch the stale color bleeds through wherever
+ * native chrome and the WebContents meet. On Windows/Linux (in-window menu
+ * bar) it shows as a light hairline between the menu bar and the page; on
+ * macOS (global menu bar) it is latent — only a wrong-color flash on resize.
+ * 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.
+ *
+ * Returns a Disposable that detaches the listener. Install it once during
+ * app setup and hand the Disposable to the workbench registry.
+ */
+export declare function installThemeBackgroundSync(): Disposable;
 //# sourceMappingURL=theme.d.ts.map

package/dist/main/utils/theme.js

@@ -1,4 +1,5 @@
-import { nativeTheme } from 'electron';
+import { BrowserWindow, nativeTheme } from 'electron';
+import { toDisposable } from './disposable.js';
 /**
  * Background color that matches the current system color scheme.
  * Pass as `backgroundColor` when creating BrowserWindows to prevent
@@ -10,4 +11,40 @@ import { nativeTheme } from 'electron';
 export function themeBg() {
     return nativeTheme.shouldUseDarkColors ? '#1a1a1a' : '#fafafa';
 }
+/**
+ * Install a single process-wide listener that keeps every window's native
+ * `backgroundColor` in sync with the active color scheme.
+ *
+ * A window's `backgroundColor` is otherwise frozen at the value passed to its
+ * constructor: after a theme switch the stale color bleeds through wherever
+ * native chrome and the WebContents meet. On Windows/Linux (in-window menu
+ * bar) it shows as a light hairline between the menu bar and the page; on
+ * macOS (global menu bar) it is latent — only a wrong-color flash on resize.
+ * 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.
+ *
+ * Returns a Disposable that detaches the listener. Install it once during
+ * app setup and hand the Disposable to the workbench registry.
+ */
+export function installThemeBackgroundSync() {
+    const apply = () => {
+        const bg = themeBg();
+        for (const win of BrowserWindow.getAllWindows()) {
+            if (!win.isDestroyed()) {
+                win.setBackgroundColor(bg);
+            }
+        }
+    };
+    nativeTheme.on('updated', apply);
+    return toDisposable(() => {
+        nativeTheme.removeListener('updated', apply);
+    });
+}
 //# sourceMappingURL=theme.js.map

package/dist/main/windows/main-window/create.d.ts

@@ -6,6 +6,12 @@ export interface WindowOptions {
     minWidth?: number;
     minHeight?: number;
     indexHtml: string;
+    /**
+     * Absolute path to the simulator preload bundle. Registered at the session
+     * level so every frame inside the simulator <webview> gets the preload that
+     * exposes the `wx` runtime to the mini-program.
+     */
+    simulatorPreloadPath: string;
 }
 export declare function createMainWindow(opts: WindowOptions): BrowserWindow;
 //# sourceMappingURL=create.d.ts.map

package/dist/main/windows/main-window/create.js

@@ -1,12 +1,21 @@
-import { app, BrowserWindow, View, globalShortcut, session } from 'electron';
+import { app, BrowserWindow, View, session, shell } from 'electron';
+import path from 'path';
 import { getSimulatorServicewechatReferer } from '../../services/simulator/referer.js';
+import { mainPreloadPath } from '../../utils/paths.js';
 import { themeBg } from '../../utils/theme.js';
+import { applyNavigationHardening, handleWindowOpenExternal, } from '../navigation-hardening.js';
 let simulatorSessionConfigured = false;
-function configureSimulatorSession() {
+function configureSimulatorSession(simulatorPreloadPath) {
     if (simulatorSessionConfigured)
         return;
     simulatorSessionConfigured = true;
     const simulatorSession = session.fromPartition('persist:simulator');
+    // Inject the simulator preload on every frame in this session. This is the
+    // mini-program runtime entry point (exposes `wx`, page registers, etc.).
+    simulatorSession.registerPreloadScript({
+        type: 'frame',
+        filePath: simulatorPreloadPath,
+    });
     simulatorSession.webRequest.onBeforeSendHeaders((details, callback) => {
         const forcedReferer = getSimulatorServicewechatReferer();
         if (forcedReferer) {
@@ -20,12 +29,12 @@ function configureSimulatorSession() {
         headers['access-control-allow-headers'] = ['*'];
         headers['access-control-allow-methods'] = ['*'];
         headers['Cross-Origin-Opener-Policy'] = ['same-origin'];
-        headers['Cross-Origin-Embedder-Policy'] = ['require-corp'];
+        headers['Cross-Origin-Embedder-Policy'] = ['credentialless'];
         callback({ responseHeaders: headers });
     });
 }
 export function createMainWindow(opts) {
-    configureSimulatorSession();
+    configureSimulatorSession(opts.simulatorPreloadPath);
     const mainWindow = new BrowserWindow({
         width: opts.width ?? 1280,
         height: opts.height ?? 980,
@@ -35,8 +44,13 @@ export function createMainWindow(opts) {
         show: false,
         backgroundColor: themeBg(),
         webPreferences: {
-            nodeIntegration: true,
-            contextIsolation: false,
+            nodeIntegration: false,
+            contextIsolation: true,
+            // `sandbox: false` is required so the preload bundle can `require('electron')`
+            // to access contextBridge/ipcRenderer. The renderer itself runs isolated.
+            sandbox: false,
+            preload: mainPreloadPath,
+            // The simulator <webview> still relies on the webview tag; keep it enabled.
             webviewTag: true,
         },
     });
@@ -51,17 +65,59 @@ export function createMainWindow(opts) {
             }
         }
     });
-    mainWindow.webContents.on('will-attach-webview', (_event, webPreferences) => {
+    const rendererDir = path.dirname(opts.indexHtml);
+    // Restrict the main renderer to file:// URLs under the renderer bundle and
+    // route every popup through the OS browser. See navigation-hardening.ts.
+    applyNavigationHardening(mainWindow.webContents, rendererDir);
+    mainWindow.webContents.on('will-attach-webview', (event, webPreferences, params) => {
+        // Pin the simulator <webview> onto `persist:simulator` so it shares storage
+        // with the rest of the session and picks up the session-registered preload.
+        // Empirically (Electron 41) `webPreferences.partition` is the field the
+        // guest session actually consults; `params.partition` alone is a no-op,
+        // so we write both belt-and-braces.
+        ;
+        webPreferences.partition = 'persist:simulator';
+        params.partition = 'persist:simulator';
+        // The simulator <webview> intentionally runs with `contextIsolation: false`
+        // because the dimina runtime and the user-authored preload scripts share
+        // the same JavaScript realm as the page — the mini-program SDK reaches
+        // into the page's globals (e.g. AudioContext, custom registers) and
+        // attaches helpers via window-level injection. Flipping isolation on
+        // would break that contract.
         webPreferences.contextIsolation = false;
+        void event;
+    });
+    // The simulator webview's webContents only exists once attached; wire its
+    // window-open / will-navigate handlers here so popups + redirects don't
+    // pivot to file:// or arbitrary origins.
+    mainWindow.webContents.on('did-attach-webview', (_event, webviewWebContents) => {
+        webviewWebContents.setWindowOpenHandler(({ url }) => handleWindowOpenExternal(url));
+        webviewWebContents.on('will-navigate', (e, url) => {
+            try {
+                const u = new URL(url);
+                // Allow the simulator's own host (localhost dev server) plus the
+                // initial about:blank that Chromium uses before src loads.
+                if (u.protocol === 'about:')
+                    return;
+                if ((u.protocol === 'http:' || u.protocol === 'https:') &&
+                    (u.hostname === 'localhost' || u.hostname === '127.0.0.1')) {
+                    return;
+                }
+                e.preventDefault();
+                if (u.protocol === 'http:' || u.protocol === 'https:') {
+                    void shell.openExternal(url);
+                }
+            }
+            catch {
+                e.preventDefault();
+            }
+        });
     });
     mainWindow.loadFile(opts.indexHtml);
     const container = new View();
     const mainWebView = mainWindow.contentView;
     container.addChildView(mainWebView);
     mainWindow.contentView = container;
-    globalShortcut.register('CommandOrControl+Shift+I', () => {
-        mainWindow.webContents.openDevTools({ mode: 'detach' });
-    });
     return mainWindow;
 }
 //# sourceMappingURL=create.js.map

package/dist/main/windows/main-window/events.d.ts

@@ -1,9 +1,10 @@
 import type { BrowserWindow } from 'electron';
 import type { WorkbenchContext } from '../../services/workbench-context.js';
+import { type Disposable } from '../../utils/disposable.js';
 export interface MainWindowEventState {
     context?: WorkbenchContext;
     onResize?: () => void;
     onClose?: (event: Electron.Event) => void | Promise<void>;
 }
-export declare function wireMainWindowEvents(win: BrowserWindow, state?: MainWindowEventState): void;
+export declare function wireMainWindowEvents(win: BrowserWindow, state?: MainWindowEventState): Disposable;
 //# sourceMappingURL=events.d.ts.map

package/dist/main/windows/main-window/events.js

@@ -1,4 +1,7 @@
+import { globalShortcut } from 'electron';
+import { DisposableRegistry, toDisposable } from '../../utils/disposable.js';
 export function wireMainWindowEvents(win, state = {}) {
+    const registry = new DisposableRegistry();
     const mainWebView = win.contentView.children[0];
     const resizeMainWebView = () => {
         if (mainWebView) {
@@ -9,10 +12,30 @@ export function wireMainWindowEvents(win, state = {}) {
     };
     resizeMainWebView();
     win.on('resize', resizeMainWebView);
+    registry.add(toDisposable(() => {
+        win.removeListener('resize', resizeMainWebView);
+    }));
     if (state.onClose) {
-        win.on('close', (event) => {
+        const onCloseHandler = (event) => {
             void state.onClose?.(event);
-        });
+        };
+        win.on('close', onCloseHandler);
+        registry.add(toDisposable(() => {
+            win.removeListener('close', onCloseHandler);
+        }));
     }
+    // DevTools shortcut: scoped to this main window so its disposal is tied
+    // to ctx.registry. `unregisterAll()` in lifecycle remains as a process-exit
+    // safety net.
+    const devToolsAccelerator = 'CommandOrControl+Shift+I';
+    const registered = globalShortcut.register(devToolsAccelerator, () => {
+        win.webContents.openDevTools({ mode: 'detach' });
+    });
+    if (registered) {
+        registry.add(toDisposable(() => {
+            globalShortcut.unregister(devToolsAccelerator);
+        }));
+    }
+    return registry;
 }
 //# sourceMappingURL=events.js.map

package/dist/main/windows/navigation-hardening.d.ts

@@ -0,0 +1,24 @@
+import type { WebContents } from 'electron';
+/**
+ * Navigation hardening for every WebContents created by the host application
+ * (main window renderer, settings overlay, popover overlay, standalone
+ * settings window). These WebContents load the contextBridge-exposing main
+ * preload, so an unintended navigation out of the renderer bundle would
+ * expose `window.devtools.ipc` to a foreign origin.
+ *
+ * `applyNavigationHardening` installs:
+ *  - `setWindowOpenHandler`: deny popups; route http(s) through the OS browser.
+ *  - `will-navigate`: cancel any in-place navigation outside `rendererDir`;
+ *    route http(s) through the OS browser.
+ */
+/** Default popup handler: open http(s) externally, deny everything else. */
+export declare function handleWindowOpenExternal(url: string): {
+    action: 'deny';
+};
+/**
+ * Install `setWindowOpenHandler` + `will-navigate` on `wc` so it can only
+ * navigate to `file://` URLs under `rendererDir`. Safe to call once per
+ * WebContents.
+ */
+export declare function applyNavigationHardening(wc: WebContents, rendererDir: string): void;
+//# sourceMappingURL=navigation-hardening.d.ts.map

package/dist/main/windows/navigation-hardening.js

@@ -0,0 +1,55 @@
+import { shell } from 'electron';
+import path from 'path';
+import { pathToFileURL } from 'url';
+/**
+ * Navigation hardening for every WebContents created by the host application
+ * (main window renderer, settings overlay, popover overlay, standalone
+ * settings window). These WebContents load the contextBridge-exposing main
+ * preload, so an unintended navigation out of the renderer bundle would
+ * expose `window.devtools.ipc` to a foreign origin.
+ *
+ * `applyNavigationHardening` installs:
+ *  - `setWindowOpenHandler`: deny popups; route http(s) through the OS browser.
+ *  - `will-navigate`: cancel any in-place navigation outside `rendererDir`;
+ *    route http(s) through the OS browser.
+ */
+/** Default popup handler: open http(s) externally, deny everything else. */
+export function handleWindowOpenExternal(url) {
+    try {
+        const u = new URL(url);
+        if (u.protocol === 'http:' || u.protocol === 'https:') {
+            void shell.openExternal(url);
+        }
+    }
+    catch {
+        /* malformed URL — fall through to deny */
+    }
+    return { action: 'deny' };
+}
+/**
+ * Install `setWindowOpenHandler` + `will-navigate` on `wc` so it can only
+ * navigate to `file://` URLs under `rendererDir`. Safe to call once per
+ * WebContents.
+ */
+export function applyNavigationHardening(wc, rendererDir) {
+    const rendererPrefix = pathToFileURL(rendererDir + path.sep).href;
+    wc.setWindowOpenHandler(({ url }) => handleWindowOpenExternal(url));
+    wc.on('will-navigate', (event, url) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            event.preventDefault();
+            return;
+        }
+        if (parsed.protocol === 'file:' && parsed.href.startsWith(rendererPrefix)) {
+            return;
+        }
+        event.preventDefault();
+        if (parsed.protocol === 'http:' || parsed.protocol === 'https:') {
+            void shell.openExternal(url);
+        }
+    });
+}
+//# sourceMappingURL=navigation-hardening.js.map