chuijs 4.0.2 → 4.0.4

package/framework/main_window.js

@@ -0,0 +1,1234 @@
+/**
+ * Окно приложения: класс `Main` — создание окон, реестр, IPC-обработчики сервисов,
+ * глобальные клавиши и обновление.
+ *
+ * Вынесен из `index.js` отдельным модулем: точка сборки публичного API перестала быть
+ * самым большим файлом репозитория, а окно читается само по себе. Публичный доступ
+ * к классу остался прежним — `require("chuijs").Main`.
+ */
+
+const {
+    app,
+    BrowserWindow,
+    dialog,
+    ipcMain,
+    Menu,
+    nativeTheme,
+    session,
+    shell,
+    Tray,
+    webContents,
+} = require("electron");
+const path = require("path");
+const fs = require("fs");
+const url = require("node:url");
+const { store } = require("./modules/chui_store/chui_store");
+const { getDefaultIcon } = require("./modules/chui_functions");
+const {
+    BRIDGE_ARGS,
+    BRIDGE_CHANNELS,
+    SERVICES_CHANNELS,
+    APP_PATH_NAMES,
+} = require("./modules/chui_services/chui_channels");
+const {
+    Clipboard,
+    ClipboardHistory: ClipboardHistoryService,
+    Locale,
+    Print,
+    RecentDocuments,
+    Shell,
+    Shortcuts,
+    TaskbarProgress,
+    Theme,
+} = require("./modules/chui_services/chui_services");
+const { I18n } = require("./modules/chui_i18n/chui_i18n");
+const { Log } = require("./modules/chui_logger/chui_logger");
+
+/**
+ * Путь приложения по имени из белого списка.
+ *
+ * Одно правило на два канала (`APP_PATH` и `APP_PATH_SYNC`): странице не должен быть доступен
+ * произвольный каталог системы, поэтому всё, что вне `APP_PATH_NAMES`, main отклоняет. Сам
+ * `app.getPath` синхронный и без диска — именно поэтому путь можно отдавать значением.
+ */
+function appPathByName(name = String()) {
+    if (APP_PATH_NAMES.includes(name) === false) throw new Error(`Desktop.app.path: имя «${name}» вне белого списка`);
+    return app.getPath(name);
+}
+
+//VARS
+let isQuiting = false;
+
+class Main {
+    /** Имя главного окна в реестре: `main.getWindow()` возвращает именно его */
+    static MAIN_WINDOW = "main";
+    /** Preload безопасного режима (contextBridge) */
+    static SECURE_PRELOAD = path.join(__dirname, "framework/modules/chui_bridge/preload.js");
+    /**
+     * Строгая политика для безопасных окон: скрипты и стили только свои (и файлы приложения),
+     * никаких внешних источников, `connect-src 'none'` — окну не нужна сеть.
+     */
+    static SECURE_CSP =
+        "default-src 'none'; script-src 'self' file:; style-src 'self' file: 'unsafe-inline'; img-src 'self' file: data: blob:; font-src 'self' file: data:; media-src 'self' file: data: blob:; connect-src 'none'";
+    /**
+     * Разметка страницы окна: пустая оболочка без собственного кода — всё приходит из
+     * preload'а приложения (обычный режим) или из моста (`security: {contextIsolation: true}`,
+     * он подключает `render` как `<script>` документа). Файлом в пакете не лежит: страница
+     * пишется в userData при первом окне — см. `#windowPage()`. Окно живёт на `file:`
+     * документе, потому что только так Chromium разрешает подключать файлы фреймворка.
+     */
+    static WINDOW_PAGE =
+        '<!DOCTYPE html><html lang="ru"><head><meta charset="UTF-8"><title>app</title></head><body></body></html>';
+    /** Путь к уже записанной странице окна: файл готовится один раз на процесс */
+    static #windowPagePath = undefined;
+    #tray = undefined;
+    //
+    #appIcon = undefined;
+    #window = undefined;
+    // Реестр окон: имя → BrowserWindow (дополнительные окна создаёт createWindow())
+    #windows = new Map();
+    #beforeQuitBound = false;
+    #webRequestBound = false;
+    //
+    #appName = undefined;
+    #height = undefined;
+    #width = undefined;
+    #minHeight = undefined;
+    #minWidth = undefined;
+    #renderer = undefined;
+    #devTools = false;
+    #devToolsOpened = false;
+    #webSecurity = true;
+    #resizable = true;
+    // IPC: обработчики регистрируются один раз и снимаются в stop()/restart()
+    #ipcRegistered = false;
+    #updaterListening = false;
+    #lastUpdateInfo = undefined;
+    #onShowSystemNotification = (e, title, body) => {
+        const { Notification } = require("electron");
+        new Notification({ title, body }).show();
+    };
+    #onSendLogText = (e, text, type) => {
+        if (type === "info") {
+            console.info(text);
+        } else if (type === "error") {
+            console.error(text);
+        }
+        this.#writeLog(text);
+    };
+    #onUpdateInstallConfirm = (e, check) => {
+        if (check) {
+            Log.info("Установка обновления...");
+            require("electron-updater").autoUpdater.quitAndInstall();
+        }
+    };
+    #onUpdateDownloaded = async () => {
+        await this.#sendNotificationUpdateLoadClose();
+        await this.#sendNotificationUpdate(this.#appName, I18n.t("appLayout.update.downloaded"));
+        setTimeout(async () => await this.#sendNotificationUpdateClose(), 3000);
+        Log.info("Обновление скачано!");
+        const version =
+            this.#lastUpdateInfo === undefined ? app.getVersion() : this.#lastUpdateInfo.versionInfo.version;
+        this.#window.webContents.send("checkUpdatesTrue", true, version);
+    };
+    // Глобальные обработчики ошибок процесса: регистрируются один раз, снимаются в stop()/restart()
+    #processHandlersRegistered = false;
+    // Десктоп-сервисы (буфер, недавние, прогресс, глобальные клавиши) и их подписки по окнам
+    #servicesEnabled = false;
+    #serviceHandlers = [];
+    // Синхронные каналы снимаются не `removeHandler`, а `removeListener`: они зарегистрированы
+    // через `ipcMain.on` — см. `#handleSync`
+    #serviceSyncHandlers = [];
+    #shortcutSubscribers = new Map();
+    #shortcutWatchers = new Map();
+    #progressWindows = new Map();
+    #onThemeUpdated = undefined;
+    // Безопасный режим: preload-мост, contextIsolation и CSP вместо Node в рендерере
+    #security = { contextIsolation: false, csp: false, channels: [] };
+    #secureContents = new Set();
+    #bridgeEnabled = false;
+    #windowActionsBound = false;
+    #themeBound = false;
+    #pageMessageHandlers = new Map();
+    #onUncaughtException = (error) => {
+        Main.#logProcessError("Необработанное исключение", error);
+    };
+    #onUnhandledRejection = (reason) => {
+        Main.#logProcessError("Необработанный reject промиса", reason);
+    };
+    static #logProcessError(prefix, value) {
+        const text = `${prefix}: ${Main.#formatError(value)}`;
+        try {
+            Log.error(text);
+        } catch (e) {
+            // Сам обработчик ошибок падать не должен (например, недоступен userData для лога)
+            console.error(text, e);
+        }
+    }
+    static #formatError(value) {
+        if (value === undefined || value === null) return I18n.t("appLayout.error.unknown");
+        if (value.stack !== undefined) return value.stack;
+        return String(value);
+    }
+    // ПУТИ: папка загрузок из options.paths — применяется, только если приложение её задало
+    #downloadPath = undefined;
+    #downloadBound = false;
+    // Загрузка в заданную папку: имя файла берём у Electron, существующее не перезаписываем
+    #onWillDownload = (event, item) => {
+        if (this.#downloadPath === undefined) return;
+        if (item === undefined || typeof item.setSavePath !== "function") return;
+        const target = path.join(this.#downloadPath, item.getFilename());
+        if (fs.existsSync(target)) return;
+        try {
+            if (!fs.existsSync(this.#downloadPath)) fs.mkdirSync(this.#downloadPath, { recursive: true });
+            item.setSavePath(target);
+        } catch (error) {
+            Log.error(`Не удалось сохранить загрузку в ${this.#downloadPath}: ${Main.#formatError(error)}`);
+        }
+    };
+
+    constructor(
+        options = {
+            name: String(),
+            sizes: { height: Number(), width: Number(), minHeight: Number(), minWidth: Number() },
+            render: String(),
+            devTools: Boolean(),
+            webSecurity: Boolean(),
+            resizable: Boolean(),
+            security: { contextIsolation: Boolean(), csp: Boolean(), channels: [] },
+            paths: {
+                downloadPath: String(),
+            },
+        }
+    ) {
+        this.#appIcon = options.icon;
+        if (this.#appIcon === undefined) {
+            if (process.platform === "darwin") {
+                this.#appIcon = Main.#resizeIconTray(getDefaultIcon());
+            } else {
+                this.#appIcon = getDefaultIcon();
+            }
+        } else {
+            if (process.platform === "darwin") {
+                this.#appIcon = Main.#resizeIconTray(options.icon);
+            } else {
+                this.#appIcon = options.icon;
+            }
+        }
+        // app.commandLine.appendSwitch('--enable-features', 'OverlayScrollbar')
+        app.commandLine.appendSwitch("disable-hid-blocklist");
+        app.commandLine.appendSwitch("enable-features=OverlayScrollbar");
+        // app.commandLine.appendSwitch("disable-http-cache");
+        app.commandLine.appendSwitch("enable-transparent-visuals");
+        app.commandLine.appendSwitch("enable-gpu-rasterization", "true");
+        app.commandLine.appendSwitch("enable-native-gpu-memory-buffers", "true");
+        app.commandLine.appendSwitch("high-dpi-support", "true");
+        app.commandLine.appendSwitch("device-scale-factor", "true");
+        app.commandLine.appendSwitch("disable-touch-adjustment", "true");
+        app.commandLine.appendSwitch("main-frame-resizes-are-orientation-changes", "true");
+        app.commandLine.appendSwitch("disable-pinch", "true");
+        // Страховка на случай широкоохватного экрана: токены темы заданы в sRGB, и без этого флага
+        // Chromium пересчитывает их в профиль монитора — число в пипетке перестаёт совпадать с тем,
+        // что написано в `main_theme_style.css`. Сам по себе сдвиг тёмных тонов на Wayland он не
+        // лечит (см. ниже), поэтому это именно страховка, а не причина той правки.
+        app.commandLine.appendSwitch("force-color-profile", "srgb");
+        // На сеансе Wayland Chromium ведёт окно через протокол цветоуправления `wp_color_manager_v1`
+        // и поднимает тёмные тона: вместо токена `#1c1c1e` из `main_theme_style.css` на экране
+        // `#222223` — замер пикселя, а чёрный и белый при этом на месте, то есть кривая, а не
+        // прозрачность. С отключённым протоколом сдвиг +6 → 0, нативный Wayland остаётся.
+        // Значение флага читается из командной строки, поэтому своё добавляем к уже переданному.
+        if (
+            process.platform === "linux" &&
+            (process.env.XDG_SESSION_TYPE === "wayland" || process.env.WAYLAND_DISPLAY !== undefined)
+        ) {
+            const passed = app.commandLine.getSwitchValue("disable-features");
+            app.commandLine.appendSwitch(
+                "disable-features",
+                passed === "" ? "WaylandWpColorManagerV1" : `${passed},WaylandWpColorManagerV1`
+            );
+        }
+
+        // Без опции загрузки идут обычным путём Electron: раньше значение вычислялось и не использовалось
+        this.#downloadPath = options.paths === undefined ? undefined : options.paths.downloadPath;
+
+        // app.commandLine.appendSwitch('autoplay-policy', 'no-user-gesture-required');
+
+        // Options
+        this.#appName = options.name;
+        this.#height = options.sizes.height;
+        this.#width = options.sizes.width;
+        this.#minHeight = options.sizes.minHeight;
+        this.#minWidth = options.sizes.minWidth;
+        this.#renderer = options.render;
+        this.#webSecurity = options.webSecurity;
+        this.#resizable = options.resizable;
+        this.#devTools = options.devTools;
+        if (options.security !== undefined) this.#security = Main.#normalizeSecurity(options.security);
+    }
+
+    static #resizeIconTray(image) {
+        return require("electron").nativeImage.createFromPath(image).resize({ width: 16, height: 16 });
+    }
+
+    /** Опции безопасности окна: по умолчанию включён привычный режим (Node в рендерере) */
+    static #normalizeSecurity(security = Object()) {
+        return {
+            contextIsolation: security.contextIsolation === true,
+            csp: security.csp === undefined ? true : security.csp,
+            channels: security.channels === undefined ? [] : security.channels,
+        };
+    }
+
+    /** CSP окна: `true` — политика фреймворка, строка — своя, `false` — без политики */
+    static #cspFor(security = Object()) {
+        if (security.contextIsolation !== true) return undefined;
+        if (security.csp === false || security.csp === undefined || security.csp === null) return undefined;
+        return security.csp === true ? Main.SECURE_CSP : String(security.csp);
+    }
+
+    // Аргументы preload'а моста: путь страницы, белый список каналов и CSP
+    static #bridgeArguments(render = undefined, security = Object()) {
+        const args = [];
+        if (render !== undefined) args.push(`${BRIDGE_ARGS.RENDER}${render}`);
+        if (security.channels !== undefined && security.channels.length > 0) {
+            args.push(`${BRIDGE_ARGS.CHANNELS}${security.channels.join(",")}`);
+        }
+        const csp = Main.#cspFor(security);
+        if (csp !== undefined) args.push(`${BRIDGE_ARGS.CSP}${csp}`);
+        return args;
+    }
+
+    /**
+     * Путь к файлу страницы окна. Разметка держится строкой (`WINDOW_PAGE`), а окно грузится
+     * только с `file:` документа (у `data:`-документа Chromium запрещает подресурсы
+     * `file:` — «Not allowed to load local resource»), поэтому файл пишется в userData и
+     * перезаписывается, если его содержимое отличается от текущей разметки.
+     */
+    static #windowPage() {
+        if (Main.#windowPagePath !== undefined) return Main.#windowPagePath;
+        const page = path.join(app.getPath("userData"), "chui_window.html");
+        try {
+            if (!fs.existsSync(page) || fs.readFileSync(page, "utf8") !== Main.WINDOW_PAGE) {
+                fs.writeFileSync(page, Main.WINDOW_PAGE, "utf8");
+            }
+        } catch (error) {
+            // Без страницы окно не создать: ошибка должна дойти до вызывающего с понятным текстом
+            throw new Error(`Не удалось создать страницу окна «${page}»: ${Main.#formatError(error)}`, {
+                cause: error,
+            });
+        }
+        Main.#windowPagePath = page;
+        return page;
+    }
+
+    static #keyToChangeLower(obj, keyToChange, value) {
+        const keyToChangeLower = keyToChange.toLowerCase();
+        for (const key of Object.keys(obj)) {
+            if (key.toLowerCase() === keyToChangeLower) {
+                obj[key] = value;
+                return;
+            }
+        }
+        obj[keyToChange] = value;
+    }
+
+    /**
+     * Создаёт окно и ставит его в реестр. Главное окно (`start()`) и дополнительные
+     * (`createWindow()`) собираются одним кодом: у всех окон одинаковые webPreferences,
+     * иконка, поведение закрытия и подписка на `chui_resizable_false`.
+     */
+    #buildWindow(
+        options = {
+            name: String(),
+            title: String(),
+            sizes: Object(),
+            render: String(),
+            parent: undefined,
+            security: Object(),
+            hideOnClose: Boolean(),
+            resizable: Boolean(),
+            devTools: Boolean(),
+        }
+    ) {
+        const sizes = options.sizes === undefined ? {} : options.sizes;
+        const name = options.name === undefined ? Main.MAIN_WINDOW : options.name;
+        const resizable = options.resizable === undefined ? this.#resizable : options.resizable;
+        // У окна может быть своя политика: `createWindow({security: {...}})`
+        const security = options.security === undefined ? this.#security : Main.#normalizeSecurity(options.security);
+        const secure = security.contextIsolation === true;
+        this.#window = new BrowserWindow({
+            transparent: false,
+            width: sizes.width === undefined ? this.#width : sizes.width,
+            height: sizes.height === undefined ? this.#height : sizes.height,
+            minHeight: sizes.minHeight === undefined ? this.#minHeight : sizes.minHeight,
+            minWidth: sizes.minWidth === undefined ? this.#minWidth : sizes.minWidth,
+            name: name,
+            title: options.title === undefined ? this.#appName : options.title,
+            show: false,
+            icon: this.#appIcon,
+            roundedCorners: true,
+            // Безопасный режим: в preload идёт мост фреймворка, а скрипт приложения
+            // выполняется как обычный <script> документа (см. chui_bridge/preload.js)
+            webPreferences: secure
+                ? {
+                      plugins: false,
+                      nodeIntegration: false,
+                      contextIsolation: true,
+                      sandbox: false,
+                      preload: Main.SECURE_PRELOAD,
+                      additionalArguments: Main.#bridgeArguments(options.render, security),
+                      spellcheck: false,
+                      webviewTag: false,
+                      webSecurity: this.#webSecurity,
+                      nodeIntegrationInSubFrames: false,
+                  }
+                : {
+                      plugins: false,
+                      nodeIntegration: true,
+                      contextIsolation: false,
+                      // Рендерер окна: у дополнительных окон может быть свой скрипт
+                      preload: options.render === undefined ? this.#renderer : options.render,
+                      spellcheck: false,
+                      webviewTag: true,
+                      webSecurity: this.#webSecurity,
+                      nodeIntegrationInSubFrames: true,
+                  },
+            frame: false,
+            resizable: resizable,
+            minimizable: true,
+            maximizable: true,
+            center: true,
+            hasShadow: true,
+            parent: options.parent,
+        });
+        const window = this.#window;
+        const webContentsId = window.webContents.id;
+        const pageUrl = url.pathToFileURL(Main.#windowPage()).href;
+        this.#windows.set(name, window);
+        if (secure) {
+            this.#secureContents.add(webContentsId);
+            this.enableBridge();
+        }
+
+        this.#bindWebRequest(window);
+        // Навигация ограничена страницей приложения: у окна нет адресной строки и меню,
+        // и уехать на чужой сайт значило бы потерять приложение без выхода назад.
+        // `window.open` и `target="_blank"` (ссылки `Link`) уходят в системный браузер,
+        // а не в новое окно Electron с чужими `webPreferences`.
+        window.webContents.setWindowOpenHandler(({ url: target }) => {
+            Main.#openExternalTarget(target);
+            return { action: "deny" };
+        });
+        window.webContents.on("will-navigate", (event, target) => {
+            if (target === pageUrl) return;
+            event.preventDefault();
+            Main.#openExternalTarget(target);
+        });
+        window
+            // Путь из userData может содержать пробелы и кириллицу — приводим его к file: URL
+            .loadURL(pageUrl)
+            .then(() => this.#bindBeforeQuit())
+            .catch((error) => {
+                // Окно закрыли до конца загрузки: навигация прерывается (ERR_FAILED/ERR_ABORTED),
+                // это не ошибка загрузки и в лог попадать не должна
+                if (window.isDestroyed() || this.#windows.get(name) !== window) return;
+                const code = String((error && error.code) || "");
+                if (code === "ERR_ABORTED" || code === "ERR_FAILED") return;
+                Main.#logProcessError("Не удалось загрузить окно", error);
+            });
+
+        if ((options.devTools === undefined ? this.#devTools : options.devTools) === true) {
+            window.webContents.openDevTools();
+            if (name === Main.MAIN_WINDOW) this.#devToolsOpened = true;
+        }
+
+        // Окно могли закрыть раньше, чем истекла задержка показа: show() у уничтоженного
+        // окна бросает «Object has been destroyed» прямо в таймере и всплывает в main
+        window.on("ready-to-show", () =>
+            setTimeout(() => {
+                if (!window.isDestroyed()) window.show();
+            }, 650)
+        );
+        // Подписки глобальных клавиш привязаны к отправителю: окно закрылось — снимаем их
+        window.on("closed", () => {
+            if (this.#windows.get(name) === window) this.#windows.delete(name);
+            this.#secureContents.delete(webContentsId);
+            this.#dropShortcutSubscriptions(webContentsId);
+            this.#progressWindows.delete(webContentsId);
+        });
+
+        if (options.hideOnClose === true) {
+            window.on("close", (evt) => {
+                if (!isQuiting) evt.preventDefault();
+                window.hide();
+            });
+        }
+        if (resizable === false) {
+            window.webContents.on("did-finish-load", () => window.webContents.send("chui_resizable_false"));
+        }
+        return window;
+    }
+
+    /**
+     * Открывает внешнюю ссылку в системном браузере.
+     *
+     * Зовётся при `window.open` и попытке увести окно на другой адрес. Наружу отдаём только
+     * `http(s)`: `file:`, `javascript:` и прочие схемы — не то, что должно попадать в браузер.
+     */
+    static #openExternalTarget(target) {
+        if (typeof target !== "string" || !/^https?:\/\//i.test(target)) return;
+        shell.openExternal(target).catch((error) => Main.#logProcessError("Не удалось открыть ссылку", error));
+    }
+
+    // `before-quit` нужен один раз на приложение, а не на каждое созданное окно
+    #bindBeforeQuit() {
+        if (this.#beforeQuitBound) return;
+        this.#beforeQuitBound = true;
+        app.on("before-quit", () => {
+            isQuiting = true;
+        });
+    }
+
+    // Обход CORS при `webSecurity: false`: у сессии один слушатель, а не по одному на окно
+    #bindWebRequest(window) {
+        if (this.#webSecurity || this.#webRequestBound) return;
+        this.#webRequestBound = true;
+        window.webContents.session.webRequest.onBeforeSendHeaders((details, callback) => {
+            const { requestHeaders } = details;
+            Main.#keyToChangeLower(requestHeaders, "Access-Control-Allow-Origin", ["*"]);
+            Main.#keyToChangeLower(requestHeaders, "X-Frame-Options", ["*"]);
+            callback({ requestHeaders });
+        });
+        window.webContents.session.webRequest.onHeadersReceived((details, callback) => {
+            const { responseHeaders } = details;
+            Main.#keyToChangeLower(responseHeaders, "Access-Control-Allow-Origin", ["*"]);
+            Main.#keyToChangeLower(responseHeaders, "Access-Control-Allow-Headers", ["*"]);
+            Main.#keyToChangeLower(responseHeaders, "X-Frame-Options", ["*"]);
+            callback({
+                responseHeaders,
+                cancel: false,
+            });
+        });
+    }
+
+    /**
+     * Дополнительное окно приложения: свой скрипт рендерера (`render`), свой layout
+     * (`AppLayout` регистрирует узлы в своём документе — см. `chui_layout`) и своя запись
+     * в реестре окон. Возвращает `BrowserWindow`, поэтому вызывать нужно с `await`:
+     * окно создаётся только после `app.whenReady()`.
+     *
+     * ```javascript
+     * const win = await main.createWindow({ name: 'preview', title: 'Просмотр',
+     *     sizes: {width: 900, height: 600}, render: `${__dirname}/app/preview.js` });
+     * main.sendTo('preview', 'preview_update', payload);
+     * ```
+     */
+    async createWindow(
+        options = {
+            name: String(),
+            title: String(),
+            sizes: Object(),
+            render: String(),
+            parent: undefined,
+            security: Object(),
+            hideOnClose: Boolean(),
+            resizable: Boolean(),
+            devTools: Boolean(),
+        }
+    ) {
+        await app.whenReady();
+        this.enableServices();
+        return this.#buildWindow(options);
+    }
+
+    /** Окно по имени реестра; без имени или с `Main.MAIN_WINDOW` — главное окно */
+    getWindow(name = Main.MAIN_WINDOW) {
+        return this.#windows.get(name);
+    }
+
+    /** Главное окно приложения (создаётся в `start()`) */
+    getMainWindow() {
+        return this.#windows.get(Main.MAIN_WINDOW);
+    }
+
+    /** Все открытые окна: `[{name, window, secure}]` в порядке создания */
+    getWindows() {
+        return [...this.#windows].map(([name, window]) => ({
+            name: name,
+            window: window,
+            secure: this.#secureContents.has(window.webContents.id),
+        }));
+    }
+
+    focusWindow(name = Main.MAIN_WINDOW) {
+        const window = this.#windows.get(name);
+        if (window === undefined) return false;
+        if (window.isMinimized()) window.restore();
+        window.show();
+        window.focus();
+        return true;
+    }
+
+    /** Закрывает окно (не приложение) и убирает его из реестра */
+    closeWindow(name = Main.MAIN_WINDOW) {
+        const window = this.#windows.get(name);
+        if (window === undefined) return false;
+        window.close();
+        return true;
+    }
+
+    /** Сообщение в конкретное окно; без имени — в главное */
+    sendTo(name = Main.MAIN_WINDOW, channel = String(), ...args) {
+        const window = this.#windows.get(name);
+        if (window === undefined || window.isDestroyed()) return false;
+        window.webContents.send(channel, ...args);
+        return true;
+    }
+
+    /**
+     * Папка загрузок из `options.paths.downloadPath`: одна подписка на сессию, снимается
+     * в `#removeGlobalHandlers()`. Без опции Electron выбирает путь загрузки сам.
+     */
+    #bindDownloadPath() {
+        if (this.#downloadPath === undefined || this.#downloadBound) return;
+        this.#downloadBound = true;
+        session.defaultSession.on("will-download", this.#onWillDownload);
+    }
+
+    /**
+     * Включает десктоп-сервисы: обработчики IPC для `Desktop` (буфер, недавние документы,
+     * прогресс на иконке, глобальные клавиши) и сами сервисы main-процесса.
+     * Вызывается один раз из `start()` и `createWindow()`.
+     */
+    enableServices() {
+        if (this.#servicesEnabled) return this;
+        this.#servicesEnabled = true;
+        // Кнопки окна: каналы нужны и обычным окнам — в них `AppLayout` зовёт их по IPC,
+        // потому что `@electron/remote` в рендерере больше нет
+        this.#enableWindowActions();
+        this.services = {
+            shortcuts: new Shortcuts(),
+            shell: new Shell(),
+            clipboard: new Clipboard(),
+            recent: new RecentDocuments(),
+            progress: new TaskbarProgress(),
+            theme: new Theme(store),
+            locale: new Locale(store),
+            clipboard_history: new ClipboardHistoryService({ store: store }),
+            print: new Print(),
+        };
+        // Сохранённая тема применяется до создания окна: иначе при запуске была бы видна
+        // вспышка системной палитры
+        this.services.theme.restore();
+        // Язык применяется и в main-процессе: его строки (меню, уведомления об обновлении)
+        // собираются там же, где живёт сервис локали
+        this.services.locale.restore();
+        I18n.setLocale(this.services.locale.get(), true);
+        this.#bindThemeEvents();
+        this.#bindDownloadPath();
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_READ_TEXT, () => this.services.clipboard.readText());
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_WRITE_TEXT, (event, text) => {
+            this.services.clipboard.writeText(text);
+            // Всё, что приложение кладёт в буфер само, должно попасть в историю
+            this.services.clipboard_history.add(text);
+            this.#emitClipboardHistory();
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HISTORY_LIST, () => this.services.clipboard_history.list());
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HISTORY_ADD, (event, text) => {
+            this.services.clipboard_history.add(text);
+            this.#emitClipboardHistory();
+            return this.services.clipboard_history.list();
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HISTORY_COPY, (event, text) => {
+            this.services.clipboard_history.copy(text);
+            this.#emitClipboardHistory();
+            return this.services.clipboard_history.list();
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HISTORY_REMOVE, (event, target) => {
+            this.services.clipboard_history.remove(target);
+            this.#emitClipboardHistory();
+            return this.services.clipboard_history.list();
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HISTORY_CLEAR, () => {
+            this.services.clipboard_history.clear();
+            this.#emitClipboardHistory();
+            return this.services.clipboard_history.list();
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_HAS, (event, format) => this.services.clipboard.has(format));
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_READ_IMAGE, () => this.services.clipboard.readImageDataURL());
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_WRITE_IMAGE, (event, dataURL) => {
+            this.services.clipboard.writeImageDataURL(dataURL);
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.CLIPBOARD_CLEAR, () => {
+            this.services.clipboard.clear();
+            return true;
+        });
+        // Приложение и системные диалоги для страницы: Electron советует IPC вместо `remote`.
+        // Путь — только из белого списка, диалог и сессия — у окна-отправителя.
+        this.#handle(SERVICES_CHANNELS.APP_PATH, (event, name) => appPathByName(name));
+        // `Desktop.app.path` отвечает значением, а не промисом, поэтому у пути есть второй,
+        // синхронный канал: `sendSync` ждёт `event.returnValue`, а не ответ `handle`.
+        // Асинхронный канал выше оставлен — его ключ есть в карте `window.chui.services`
+        this.#handleSync(SERVICES_CHANNELS.APP_PATH_SYNC, (event, name) => appPathByName(name));
+        this.#handle(SERVICES_CHANNELS.APP_INFO, () => ({
+            name: app.getName(),
+            version: app.getVersion(),
+            locale: app.getLocale(),
+            systemLocale: app.getSystemLocale(),
+            isPackaged: app.isPackaged,
+        }));
+        // Закрытие и перезапуск со страницы: страница — код самого приложения, поэтому кнопке
+        // «Выход» не нужен свой канал в каждом проекте. Идут через `Main.stop()`/`restart()` —
+        // те же шаги, что у пункта меню: снимаются обработчики сервисов, глобальные клавиши и
+        // подписки, а не просто закрывается окно. Ответ уходит странице до выхода
+        // (`setImmediate`): иначе промис отваливался бы с «Render frame was disposed», и
+        // `await Desktop.app.quit()` со страницы выглядел бы ошибкой
+        this.#handle(SERVICES_CHANNELS.APP_QUIT, () => {
+            setImmediate(() => this.stop());
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.APP_RESTART, () => {
+            setImmediate(() => this.restart());
+            return true;
+        });
+        // У закрытия и перезапуска есть и синхронные каналы: `Desktop.app.quit()`/`restart()`
+        // отвечают значением, а не промисом — как `Desktop.app.path`. Выход по-прежнему
+        // откладывается `setImmediate`, чтобы `event.returnValue` успел уйти странице.
+        this.#handleSync(SERVICES_CHANNELS.APP_QUIT_SYNC, () => {
+            setImmediate(() => this.stop());
+            return true;
+        });
+        this.#handleSync(SERVICES_CHANNELS.APP_RESTART_SYNC, () => {
+            setImmediate(() => this.restart());
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.DIALOG_OPEN, (event, options) =>
+            Main.#showDialog(event, "showOpenDialog", options)
+        );
+        this.#handle(SERVICES_CHANNELS.DIALOG_SAVE, (event, options) =>
+            Main.#showDialog(event, "showSaveDialog", options)
+        );
+        this.#handle(SERVICES_CHANNELS.DIALOG_MESSAGE, (event, options) =>
+            Main.#showDialog(event, "showMessageBox", options)
+        );
+        this.#handle(SERVICES_CHANNELS.SESSION_CACHE_SIZE, (event) => event.sender.session.getCacheSize());
+        this.#handle(SERVICES_CHANNELS.SESSION_CLEAR_CACHE, (event) => event.sender.session.clearCache());
+        this.#handle(SERVICES_CHANNELS.SESSION_CLEAR_STORAGE, (event, options) =>
+            event.sender.session.clearStorageData(options)
+        );
+        this.#handle(SERVICES_CHANNELS.RECENT_ADD, (event, path, name) => {
+            this.services.recent.add(path, name);
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.RECENT_CLEAR, () => {
+            this.services.recent.clear();
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.RECENT_LIST, () => this.services.recent.get());
+        this.#handle(SERVICES_CHANNELS.PROGRESS_SET, (event, value, mode) => {
+            this.#progressFor(event).set(value, mode);
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.PROGRESS_CLEAR, (event) => {
+            this.#progressFor(event).clear();
+            return true;
+        });
+        this.#handle(SERVICES_CHANNELS.SHELL_OPEN_EXTERNAL, (event, url) => this.services.shell.openExternal(url));
+        this.#handle(SERVICES_CHANNELS.PRINT_PAGE, (event, options) =>
+            this.services.print.page(BrowserWindow.fromWebContents(event.sender), this.#printOptions(event, options))
+        );
+        this.#handle(SERVICES_CHANNELS.PRINT_HTML, (event, html, options) =>
+            this.services.print.html(html, this.#printOptions(event, options))
+        );
+        this.#handle(SERVICES_CHANNELS.PRINT_PDF, (event, html, options) =>
+            this.services.print.pdf(html, this.#printOptions(event, options))
+        );
+        this.#handle(SERVICES_CHANNELS.THEME_GET, () => ({
+            theme: this.services.theme.get(),
+            source: this.services.theme.getSource(),
+        }));
+        this.#handle(SERVICES_CHANNELS.THEME_SET, (event, source) => {
+            this.services.theme.set(source);
+            return { theme: this.services.theme.get(), source: this.services.theme.getSource() };
+        });
+        this.#handle(SERVICES_CHANNELS.THEME_TOGGLE, () => {
+            this.services.theme.toggle();
+            return { theme: this.services.theme.get(), source: this.services.theme.getSource() };
+        });
+        this.#handle(SERVICES_CHANNELS.LOCALE_GET, () => this.services.locale.get());
+        this.#handle(SERVICES_CHANNELS.LOCALE_SET, (event, locale) => {
+            const applied = this.services.locale.set(locale);
+            // Язык main-процесса меняется вместе с окнами: иначе меню и уведомления об обновлении
+            // остались бы на прежнем языке
+            I18n.setLocale(applied, true);
+            // Локаль, в отличие от темы, не имеет системного события — окна узнают о смене отсюда
+            this.#emitLocale(applied);
+            return applied;
+        });
+        this.#handle(SERVICES_CHANNELS.SHORTCUT_SUBSCRIBE, (event, accelerator) =>
+            this.#subscribeShortcut(event, accelerator)
+        );
+        this.#handle(SERVICES_CHANNELS.SHORTCUT_UNSUBSCRIBE, (event, accelerator) => {
+            this.#unsubscribeShortcut(event, accelerator);
+            return true;
+        });
+        return this;
+    }
+
+    // ipcMain.handle + запись для снятия в stop()/restart()
+    #handle(channel = String(), handler = () => {}) {
+        ipcMain.handle(channel, handler);
+        this.#serviceHandlers.push([channel, handler]);
+        return this;
+    }
+
+    /**
+     * Синхронный канал: `ipcRenderer.sendSync` в странице ждёт `event.returnValue`, а не ответ
+     * `handle`, поэтому здесь `ipcMain.on`. Ответ — конверт `{value}`/`{error}`: у синхронного
+     * канала нет способа передать исключение, и без конверта страница получила бы `undefined`
+     * вместо причины отказа (см. `SERVICES_SYNC_CALLS` в chui_channels.js).
+     */
+    #handleSync(channel = String(), handler = () => {}) {
+        const listener = (event, ...args) => {
+            try {
+                event.returnValue = { value: handler(event, ...args) };
+            } catch (error) {
+                event.returnValue = { error: error instanceof Error ? error.message : String(error) };
+            }
+        };
+        ipcMain.on(channel, listener);
+        this.#serviceSyncHandlers.push([channel, listener]);
+        return this;
+    }
+
+    /**
+     * Включает мост безопасных окон (`contextBridge`): управление окном, тема и прикладные
+     * сообщения по белому списку каналов. Вызывается сам при создании безопасного окна.
+     */
+    /** Диалог в окне отправителя: без окна (уже закрыто) Electron зовётся без родителя */
+    static #showDialog(event, method = String(), options = Object()) {
+        const window = BrowserWindow.fromWebContents(event.sender);
+        return window === null ? dialog[method](options) : dialog[method](window, options);
+    }
+
+    /**
+     * Каналы кнопок окна. Ими пользуются оба режима: безопасное окно — через мост
+     * `window.chui.window`, обычное — прямым `ipcRenderer.invoke`. Регистрируются один раз на приложение.
+     */
+    #enableWindowActions() {
+        if (this.#windowActionsBound) return this;
+        this.#windowActionsBound = true;
+        this.#handle(BRIDGE_CHANNELS.WINDOW_ACTION, (event, action) => Main.#applyWindowAction(event.sender, action));
+        this.#handle(BRIDGE_CHANNELS.WINDOW_STATE, (event) => {
+            const window = BrowserWindow.fromWebContents(event.sender);
+            if (window === null) return {};
+            return {
+                isMaximized: window.isMaximized(),
+                isMinimized: window.isMinimized(),
+                isFullScreen: window.isFullScreen(),
+                isFocused: window.isFocused(),
+            };
+        });
+        return this;
+    }
+
+    enableBridge() {
+        if (this.#bridgeEnabled) return this;
+        this.#bridgeEnabled = true;
+        this.#enableWindowActions();
+        this.#handle(BRIDGE_CHANNELS.THEME_GET, () => (nativeTheme.shouldUseDarkColors ? "dark" : "light"));
+        this.#handle(BRIDGE_CHANNELS.LOCALE_GET, () => this.services.locale.get());
+        this.#handle(BRIDGE_CHANNELS.MESSAGE, (event, channel, ...args) => {
+            const handler = this.#pageMessageHandlers.get(channel);
+            if (handler === undefined) return { handled: false };
+            return handler(...args, event);
+        });
+        this.#bindThemeEvents();
+        return this;
+    }
+
+    /**
+     * Обработчик сообщений из безопасного окна. Канал должен быть указан в
+     * `security: {channels: [...]}`, иначе мост его не отправит.
+     *
+     * ```javascript
+     * main.onPageMessage('preview:save', (payload) => console.log(payload));
+     * main.sendToPage('preview:update', {ready: true}, 'preview');
+     * ```
+     */
+    onPageMessage(channel = String(), handler = () => {}) {
+        this.enableBridge();
+        this.#pageMessageHandlers.set(channel, handler);
+        return this;
+    }
+
+    /** Сообщение в страницу безопасного окна: его `messaging.on(channel)` получит полезную нагрузку */
+    sendToPage(channel = String(), payload = undefined, windowName = undefined) {
+        return this.#send(BRIDGE_CHANNELS.MESSAGE, [channel, payload], windowName);
+    }
+
+    /** Действия кнопок окна: и обычные окна, и безопасные зовут их по IPC */
+    static #applyWindowAction(sender, action = String()) {
+        const window = BrowserWindow.fromWebContents(sender);
+        if (window === null || window.isDestroyed()) return false;
+        if (action === "minimize") window.minimize();
+        else if (action === "toggle-maximize") {
+            if (window.isMaximized()) window.unmaximize();
+            else window.maximize();
+        } else if (action === "restore") window.restore();
+        else if (action === "toggle-fullscreen") window.setFullScreen(!window.isFullScreen());
+        else if (action === "close") window.close();
+        else return false;
+        return true;
+    }
+
+    // Смена темы: системную ловим событием Electron, выбранную пользователем — сами.
+    // Слушатель один на приложение, окна получают событие по своим каналам
+    #bindThemeEvents() {
+        if (this.#themeBound) return;
+        this.#themeBound = true;
+        this.#onThemeUpdated = () => this.#emitTheme();
+        nativeTheme.on("updated", this.#onThemeUpdated);
+    }
+
+    /**
+     * Сообщить окнам текущую тему. Обычные окна слушают `Desktop.theme.onChange`,
+     * безопасные — мост `window.chui.theme.onChange`.
+     *
+     * Вызывается из события `nativeTheme` — оно приходит и от системы, и после
+     * `theme.set()/toggle()` (Electron сообщает о смене `shouldUseDarkColors`).
+     * Поэтому обработчики IPC ничего дополнительно не рассылают: смену источника
+     * без смены палитры подписчикам темы сообщать не о чем.
+     */
+    #emitTheme() {
+        const theme = nativeTheme.shouldUseDarkColors ? "dark" : "light";
+        for (const window of this.#windows.values()) {
+            if (window.isDestroyed()) continue;
+            window.webContents.send(SERVICES_CHANNELS.THEME_EVENT, theme);
+        }
+        for (const id of this.#secureContents) {
+            const contents = webContents.fromId(id);
+            if (contents === undefined || contents.isDestroyed()) continue;
+            contents.send(BRIDGE_CHANNELS.THEME_EVENT, theme);
+        }
+    }
+
+    /**
+     * Сообщить окнам текущий язык. Обычные окна слушают `Desktop.locale.onChange`,
+     * безопасные — мост `window.chui.locale.onChange`.
+     */
+    #emitLocale(locale = String()) {
+        for (const window of this.#windows.values()) {
+            if (window.isDestroyed()) continue;
+            window.webContents.send(SERVICES_CHANNELS.LOCALE_EVENT, locale);
+        }
+        for (const id of this.#secureContents) {
+            const contents = webContents.fromId(id);
+            if (contents === undefined || contents.isDestroyed()) continue;
+            contents.send(BRIDGE_CHANNELS.LOCALE_EVENT, locale);
+        }
+    }
+
+    /** История буфера меняется в main — панели в окнах обновляются по этому событию */
+    #emitClipboardHistory() {
+        const items = this.services.clipboard_history.list();
+        for (const window of this.#windows.values()) {
+            if (window.isDestroyed()) continue;
+            window.webContents.send(SERVICES_CHANNELS.CLIPBOARD_HISTORY_EVENT, items);
+        }
+    }
+
+    // Прогресс считаем по окну-отправителю: у каждого окна своя иконка
+    #progressFor(event) {
+        const id = event.sender.id;
+        let progress = this.#progressWindows.get(id);
+        if (progress === undefined) {
+            progress = new TaskbarProgress(BrowserWindow.fromWebContents(event.sender));
+            this.#progressWindows.set(id, progress);
+        }
+        return progress;
+    }
+
+    /**
+     * Подписка окна на глобальную клавишу. Клавиша регистрируется один раз на все окна;
+     * `false` в ответе означает, что комбинацию занял другой процесс.
+     */
+    #subscribeShortcut(event, accelerator = String()) {
+        const id = event.sender.id;
+        const subscribers = this.#shortcutSubscribers.get(accelerator) ?? new Set();
+        const first = subscribers.size === 0;
+        if (first && !this.services.shortcuts.register(accelerator, () => this.#emitShortcut(accelerator))) {
+            return false;
+        }
+        subscribers.add(id);
+        this.#shortcutSubscribers.set(accelerator, subscribers);
+        const watched = this.#shortcutWatchers.get(id) ?? new Set();
+        watched.add(accelerator);
+        this.#shortcutWatchers.set(id, watched);
+        return true;
+    }
+
+    #unsubscribeShortcut(event, accelerator = String()) {
+        const id = event.sender.id;
+        const subscribers = this.#shortcutSubscribers.get(accelerator);
+        if (subscribers !== undefined) {
+            subscribers.delete(id);
+            if (subscribers.size === 0) {
+                this.#shortcutSubscribers.delete(accelerator);
+                this.services.shortcuts.unregister(accelerator);
+            }
+        }
+        const watched = this.#shortcutWatchers.get(id);
+        if (watched !== undefined) {
+            watched.delete(accelerator);
+            if (watched.size === 0) this.#shortcutWatchers.delete(id);
+        }
+    }
+
+    /**
+     * Опции печати из окна: диалог сохранения PDF должен быть модальным к окну-отправителю,
+     * поэтому `parent` берём из события, а не из запроса страницы.
+     */
+    #printOptions(event, options = Object()) {
+        return { ...options, parent: BrowserWindow.fromWebContents(event.sender) };
+    }
+
+    #emitShortcut(accelerator = String()) {
+        const subscribers = this.#shortcutSubscribers.get(accelerator);
+        if (subscribers === undefined) return;
+        for (const id of [...subscribers]) {
+            const contents = webContents.fromId(id);
+            if (contents === undefined || contents.isDestroyed()) continue;
+            contents.send(SERVICES_CHANNELS.SHORTCUT_EVENT, accelerator);
+        }
+    }
+
+    // Окно закрылось: его подписки больше не нужны, а осиротевшие клавиши освобождаем
+    #dropShortcutSubscriptions(webContentsId = Number()) {
+        const watched = this.#shortcutWatchers.get(webContentsId);
+        if (watched === undefined) return;
+        this.#shortcutWatchers.delete(webContentsId);
+        for (const accelerator of watched) {
+            const subscribers = this.#shortcutSubscribers.get(accelerator);
+            if (subscribers === undefined) continue;
+            subscribers.delete(webContentsId);
+            if (subscribers.size !== 0) continue;
+            this.#shortcutSubscribers.delete(accelerator);
+            this.services.shortcuts.unregister(accelerator);
+        }
+    }
+
+    toggleDevTools(name = Main.MAIN_WINDOW) {
+        const window = this.#windows.get(name);
+        if (window === undefined) return false;
+        if (this.#devToolsOpened && name === Main.MAIN_WINDOW) {
+            window.webContents.closeDevTools();
+            this.#devToolsOpened = false;
+            return true;
+        }
+        window.webContents.openDevTools();
+        if (name === Main.MAIN_WINDOW) this.#devToolsOpened = true;
+        return true;
+    }
+
+    #hideAndShow() {
+        const window = this.#targetWindow();
+        if (window === undefined) return;
+        const visible = window.isVisible();
+        const focus = window.isFocused();
+
+        if (visible && focus) {
+            window.hide();
+        } else if (!visible && !focus) {
+            window.show();
+        } else {
+            window.focus();
+        }
+    }
+
+    // Окно-адресат: по умолчанию главное, но уведомление можно отправить и в своё окно
+    #targetWindow(name = undefined) {
+        return this.#windows.get(name === undefined ? Main.MAIN_WINDOW : name) ?? this.#window;
+    }
+
+    #send(channel = String(), args = [], windowName = undefined) {
+        const window = this.#targetWindow(windowName);
+        if (window === undefined || window.isDestroyed()) return false;
+        window.webContents.send(channel, ...args);
+        return true;
+    }
+
+    stop() {
+        this.#removeGlobalHandlers();
+        if (process.platform !== "darwin") {
+            app.quit();
+        } else {
+            app.exit(0);
+        }
+    }
+
+    restart() {
+        this.#removeGlobalHandlers();
+        app.relaunch();
+        app.exit(0);
+    }
+
+    #removeGlobalHandlers() {
+        ipcMain.removeListener("show_system_notification", this.#onShowSystemNotification);
+        ipcMain.removeListener("SEND_LOG_TEXT", this.#onSendLogText);
+        ipcMain.removeListener("updateInstallConfirm", this.#onUpdateInstallConfirm);
+        // Папка загрузок: подписка на сессию снимается вместе с остальными глобальными обработчиками
+        if (this.#downloadBound) {
+            this.#downloadBound = false;
+            session.defaultSession.removeListener("will-download", this.#onWillDownload);
+        }
+        // Десктоп-сервисы: снимаем обработчики IPC, подписки клавиш и сами клавиши
+        for (const [channel] of this.#serviceHandlers) ipcMain.removeHandler(channel);
+        this.#serviceHandlers = [];
+        for (const [channel, listener] of this.#serviceSyncHandlers) ipcMain.removeListener(channel, listener);
+        this.#serviceSyncHandlers = [];
+        this.#shortcutSubscribers.clear();
+        this.#shortcutWatchers.clear();
+        this.#progressWindows.clear();
+        if (this.services !== undefined) this.services.shortcuts.destroy();
+        this.#servicesEnabled = false;
+        // Мост безопасных окон: обработчики ipcMain уже сняты выше, остались события темы
+        if (this.#themeBound && this.#onThemeUpdated !== undefined) {
+            nativeTheme.removeListener("updated", this.#onThemeUpdated);
+        }
+        this.#themeBound = false;
+        this.#onThemeUpdated = undefined;
+        this.#pageMessageHandlers.clear();
+        this.#bridgeEnabled = false;
+        this.#windowActionsBound = false;
+        if (this.#updaterListening) {
+            this.#updaterListening = false;
+            require("electron-updater").autoUpdater.removeListener("update-downloaded", this.#onUpdateDownloaded);
+        }
+        if (this.#processHandlersRegistered) {
+            this.#processHandlersRegistered = false;
+            process.removeListener("uncaughtException", this.#onUncaughtException);
+            process.removeListener("unhandledRejection", this.#onUnhandledRejection);
+        }
+        this.#ipcRegistered = false;
+    }
+
+    start(options = { hideOnClose: Boolean(), globalMenu: [], tray: [], extensions: [] }) {
+        nativeTheme.themeSource = "system";
+        // Обработчики процесса — один раз на экземпляр Main (иначе копились при повторном start())
+        if (this.#ipcRegistered === false) {
+            this.#ipcRegistered = true;
+            ipcMain.on("show_system_notification", this.#onShowSystemNotification);
+            ipcMain.on("SEND_LOG_TEXT", this.#onSendLogText);
+        }
+        // Необработанные ошибки main-процесса — в тот же лог, что и Log.error (консоль + файл)
+        if (this.#processHandlersRegistered === false) {
+            this.#processHandlersRegistered = true;
+            process.on("uncaughtException", this.#onUncaughtException);
+            process.on("unhandledRejection", this.#onUnhandledRejection);
+        }
+
+        app.whenReady().then(() => {
+            session.defaultSession.setPermissionRequestHandler((webContents, permission, callback) => {
+                if (permission === "media") {
+                    callback(true); // Approve microphone/camera access
+                } else {
+                    callback(false);
+                }
+            });
+
+            if (options.extensions) {
+                for (const extension of options.extensions)
+                    session.defaultSession
+                        .loadExtension(extension)
+                        .then((r) => Log.info(r))
+                        .catch((e) => Log.error(e));
+            }
+            if (options.tray) {
+                this.#tray = new Tray(this.#appIcon);
+                const context = Menu.buildFromTemplate(options.tray);
+                this.#tray.setContextMenu(context);
+
+                this.#tray.on("click", () => this.#hideAndShow());
+            }
+            if (options.globalMenu) {
+                const menu = Menu.buildFromTemplate(options.globalMenu);
+                Menu.setApplicationMenu(menu);
+            } else {
+                Menu.setApplicationMenu(null);
+            }
+            this.enableServices();
+            this.#buildWindow({ name: Main.MAIN_WINDOW, hideOnClose: options.hideOnClose });
+        });
+    }
+
+    #writeLog(text) {
+        const today = new Date().toLocaleDateString().replace("/", ".");
+        const logDirPath = path.join(app.getPath("userData"), "logs");
+        const logFilePath = path.join(logDirPath, `app_${today}.log`);
+
+        if (!fs.existsSync(logDirPath)) {
+            fs.mkdirSync(logDirPath, { recursive: true });
+            fs.writeFileSync(logFilePath, "", "utf-8");
+        }
+
+        fs.writeFile(logFilePath, `${text}\n`, { flag: "a+" }, (err) => {
+            if (err) console.error(err);
+        });
+    }
+
+    enableAutoUpdateApp(start = Number()) {
+        const { autoUpdater } = require("electron-updater");
+        // Подписки на апдейтер и подтверждение установки — один раз на экземпляр Main:
+        // раньше ipcMain.on("updateInstallConfirm") и autoUpdater.on добавлялись
+        // внутри update-downloaded, то есть на каждое событие.
+        if (this.#updaterListening === false) {
+            this.#updaterListening = true;
+            autoUpdater.on("update-downloaded", this.#onUpdateDownloaded);
+            ipcMain.on("updateInstallConfirm", this.#onUpdateInstallConfirm);
+        }
+        setTimeout(async () => {
+            autoUpdater.autoInstallOnAppQuit = false;
+            const updates = await autoUpdater.checkForUpdates();
+            if (updates !== null) {
+                this.#lastUpdateInfo = updates;
+                if (updates.versionInfo.version > app.getVersion()) {
+                    await this.#sendNotificationUpdateLoad(
+                        this.#appName,
+                        I18n.t("appLayout.update.downloading", { version: updates.versionInfo.version })
+                    );
+                }
+            }
+        }, start);
+    }
+    async #sendNotificationUpdateLoad(text, body) {
+        this.#send("sendNotificationUpdateLoad", [text, body]);
+    }
+    async #sendNotificationUpdateLoadClose() {
+        this.#send("sendNotificationUpdateLoadClose");
+    }
+    async #sendNotificationUpdate(text, body) {
+        this.#send("sendNotificationUpdate", [text, body]);
+    }
+    async #sendNotificationUpdateClose() {
+        this.#send("sendNotificationUpdateClose");
+    }
+
+    /** Уведомление о загрузке; последним аргументом можно указать окно реестра */
+    sendDownload(text, body, windowName = undefined) {
+        setTimeout(() => this.#send("sendNotificationDownload", [text, body], windowName), 1);
+    }
+    sendDownloadUpdate(text, body, windowName = undefined) {
+        setTimeout(() => this.#send("sendNotificationDownloadUpdate", [text, body], windowName), 1);
+    }
+    sendDownloadComplete(text, body, windowName = undefined) {
+        setTimeout(() => this.#send("sendNotificationDownloadComplete", [text, body], windowName), 250);
+    }
+    sendDownloadError(text, body, windowName = undefined) {
+        setTimeout(() => this.#send("sendNotificationDownloadError", [text, body], windowName), 250);
+    }
+}
+
+exports.Main = Main;