chuijs 4.0.1 → 4.0.2

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 Формат — [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
 версии — [Semantic Versioning](https://semver.org/lang/ru/).
 
+## [4.0.2] - 2026-09-29
+
+### Исправлено
+
+- **Заголовок страницы вернулся в шапку.** `Route#go()` больше не подмешивает название в
+  содержимое: узел `page_title` (появился в 4.0.1) и его стили удалены. Он дублировал заголовок,
+  который страница рисует сама, а `Page#render()` отдаёт один и тот же узел — повторный переход
+  на ту же страницу (кнопка «Назад» из `Page#setBackButton()`) добавлял второй заголовок.
+  Название показывает узел `page_name` в шапке, у страницы с меню-баром он по-прежнему скрыт —
+  место занимает полоса меню.
+
+### Изменено
+
+- **`Desktop.app.path()` отвечает значением, а не промисом.** Из путей страница собирает свои
+  (файлы, логи, кеш) на старте, где `await` пришлось бы протаскивать через весь код инициализации.
+  Путь приходит по синхронному каналу (`SERVICES_SYNC_CALLS`: `ipcRenderer.sendSync` в странице,
+  `ipcMain.on` + `event.returnValue` в main) и кешируется — за одним именем в main ходят один раз.
+  Ответ идёт конвертом `{value}`/`{error}`: у `sendSync` нет канала для исключения, поэтому отказ
+  (имя вне белого списка) приходит странице обычной ошибкой с текстом main. Прежний
+  `await Desktop.app.path(...)` продолжает работать — `await` на строке возвращает ту же строку.
+  Асинхронный канал `APP_PATH` оставлен: его ключ есть в карте `window.chui.services`.
+
+### Добавлено
+
+- **`Desktop.app.quit()` и `Desktop.app.restart()`** — закрытие и перезапуск приложения со страницы,
+  в том числе из безопасного окна (`window.chui.desktop.app.quit()`). Идут через `Main.stop()`/
+  `Main.restart()`, то есть теми же шагами, что пункт меню «Выход»: снимаются обработчики сервисов,
+  глобальные клавиши и подписки, а не просто закрывается окно. Отвечают значением, а не промисом
+  (синхронные каналы `appQuitSync`/`appRestartSync`), поэтому `await` не обязателен; выход
+  откладывается `setImmediate`, чтобы ответ успел уйти странице. Асинхронные каналы
+  `APP_QUIT`/`APP_RESTART` оставлены: их ключи есть в карте `window.chui.services`.
+- Тесты `test/chui_services_sync.test.js` и `test/chui_app_lifecycle.test.js`: сверяют синхронные
+  каналы (main ↔ мост preload ↔ страница) и то, что закрытие с перезапуском идут именно через
+  `Main.stop()`/`Main.restart()`.
+
+### Удалено
+
+- **Класс `App` и вспомогательный `Application` удалены.** `App.get()`, `App.getSession()`,
+  `App.getWebContents()` и все `App.*Path()` больше не экспортируются. Пути теперь отдаёт
+  `Desktop.app.path(name)` — и на странице, и в main-процессе: там канала нет, поэтому путь
+  берётся у Electron напрямую с той же проверкой белого списка `APP_PATH_NAMES`. Сырые объекты
+  Electron в main отдают `Desktop.app.get()`, `Desktop.app.getSession()` и
+  `Desktop.app.getWebContents()`; со страницы они бросают ошибку с подсказкой (`Desktop.session.*`,
+  `Desktop.dialog` или свой канал из `security.channels`).
+  **Ломающее:** `const { App } = require('chuijs')` перестаёт работать.
+- Тест `test/chui_app_paths.test.js` переписан: сверяет белый список с ожидаемым набором имён
+  путей и проверяет оба валидатора — `appPathByName` (`index.js`) и `#appPathInMain` (`desktop.js`).
+
+### Пакет
+
+- Версия 4.0.2.
+
 ## [4.0.1] - 2026-09-28
 
 ### Добавлено

package/README.md

@@ -60,7 +60,7 @@ render(() => new App()).catch(err => Log.error(err))
 #### exampleApp / main.js
 ```javascript
 /** main.js */
-const { Main, MenuItem, path, App } = require('chuijs');
+const { Main, MenuItem, path, Desktop } = require('chuijs');
 const main = new Main({
     name: "exampleApp",
     // размеры окна задаются вложенным объектом sizes
@@ -73,9 +73,9 @@ const main = new Main({
     render: `${__dirname}/app/app.js`,
     devTools: false,
     resizable: true,
-    // папка загрузок (по умолчанию App.downloadsPath())
+    // папка загрузок: если не задана, путь выбирает Electron
     paths: {
-        downloadPath: path.join(App.userDataPath(), "downloads")
+        downloadPath: path.join(Desktop.app.path("userData"), "downloads")
     }
     /** icon: `${__dirname}/resources/icons/app/icon.png` */
 });
@@ -95,8 +95,9 @@ main.start({
 > поэтому окно доступно через `main.getWindow()` только после старта.
 #### Download Session в main.js
 ```javascript
-const { App } = require('chuijs');
-App.get().on('session-created', (session) => {
+const { Desktop } = require('chuijs');
+const app = Desktop.app.get();      // сырой `app` — только в main-процессе
+app.on('session-created', (session) => {
     session.on('will-download', (e, item, contents) => {
         // ...
     });
@@ -124,14 +125,14 @@ async function run() {
 Создаёт окно, трей и управляет жизненным циклом приложения.
 
 ```javascript
-const { Main, MenuItem, App } = require('chuijs');
+const { Main, MenuItem, Desktop } = require('chuijs');
 const main = new Main({
     name: 'exampleApp',
     sizes: { width: 1366, height: 768, minWidth: 960, minHeight: 540 },
     render: `${__dirname}/app/app.js`,
     devTools: false,
     resizable: true,
-    paths: { downloadPath: path.join(App.userDataPath(), 'downloads') }
+    paths: { downloadPath: path.join(Desktop.app.path('userData'), 'downloads') }
 });
 main.start({ hideOnClose: false, tray: [new MenuItem().quit('Выход')] });
 ```
@@ -178,32 +179,37 @@ main.getWindows();                                    // [{name, window}, …]
 `stop()` и `restart()` снимают свои обработчики: IPC (`show_system_notification`, `SEND_LOG_TEXT`,
 `updateInstallConfirm`), обработчики десктоп-сервисов вместе с глобальными клавишами,
 подписку апдейтера и глобальные обработчики ошибок процессов —
-повторный `start()` подпишет их заново по одному разу.
+повторный `start()` подпишет их заново по одному разу. Со страницы то же делают
+`Desktop.app.quit()` и `Desktop.app.restart()`: страница — код самого приложения, поэтому своей
+кнопке «Выход» не нужен отдельный канал в каждом проекте. Оба отвечают значением, а не промисом
+(синхронный канал, как у `Desktop.app.path`), поэтому `await` не обязателен.
 
-#### `App`
-Обёртка над `app` Electron. **Только для main-процесса:** странице модули main не отдают
-(Electron не рекомендует `remote`), и её `App.get*` бросает ошибку с подсказкой. Со страницы
-берут `Desktop.app`, `Desktop.session`, `Desktop.dialog` или свой канал из `security.channels`.
+Пути приложения отдаёт `Desktop.app.path(name)` — и в main-процессе, и на странице, значением
+без промиса (на странице — синхронным каналом, в main — прямо у Electron):
 
 ```javascript
-const { App } = require('chuijs');
-App.get();             // app
-App.getSession();      // session
-App.getWebContents();  // webContents
+const { Desktop } = require('chuijs');
+Desktop.app.path('userData');     // .../AppData/<name>
+Desktop.app.path('downloads');
+Desktop.app.path('logs');
 ```
 
-#### `App.*Path()`
-Статические системные пути (все возвращают строку). **Только для main-процесса;** со страницы —
-`await Desktop.app.path('userData')` (там путь приходит по IPC и потому асинхронно).
+Имена берутся из белого списка: `home`, `appData`, `userData`, `sessionData`, `temp`, `exe`,
+`module`, `desktop`, `documents`, `downloads`, `music`, `pictures`, `videos`, `logs`, `recent`,
+`crashDumps`; всё, что вне списка, отклоняется. Со страницы то же значение доступно как
+`window.chui.desktop.app.path('userData')`.
+
+Сырые объекты Electron (`app`, `session`, `webContents`) странице не отдают — Electron не
+рекомендует `remote`. В main-процессе их отдают `Desktop.app.get()`, `Desktop.app.getSession()`
+и `Desktop.app.getWebContents()`:
 
 ```javascript
-const { App } = require('chuijs');
-App.userDataPath();     // .../AppData/<name>
-App.downloadsPath();
-App.logsPath();
+const app = Desktop.app.get();                   // main.js
+app.on('session-created', (session) => { /* … */ });
 ```
 
-Полный список: `homePath()`, `appDataPath()`, `userDataPath()`, `sessionDataPath()`, `logsPath()`, `tempPath()`, `exePath()`, `modulePath()`, `desktopPath()`, `documentsPath()`, `downloadsPath()`, `musicPath()`, `picturesPath()`, `videosPath()`, `recentPath()`, `crashDumpsPath()`.
+Со страницы эти методы бросают ошибку с подсказкой: вместо них берут `Desktop.session.*`,
+`Desktop.dialog` или свой канал из `security.channels`.
 
 #### `Log`
 Пишет в `userData/logs/app_<date>.log`.
@@ -280,7 +286,8 @@ await bot.sendMessage({ chat_id: '123', text: 'привет' });
 доступны только там), а страница работает с ними через `Desktop`: он сам выбирает транспорт —
 канал `ipcRenderer.invoke` в обычном режиме или методы `window.chui.services` (preload +
 `contextBridge`) в безопасном. Имена каналов лежат в одном модуле `chui_services/chui_channels`,
-поэтому main и рендерер не расходятся.
+поэтому main и рендерер не расходятся. Пути приложения — единственное исключение: они идут
+синхронным каналом (`Desktop.app.path` отвечает значением, а не промисом, см. ниже).
 
 ```javascript
 const { Desktop } = require('chuijs');
@@ -302,8 +309,11 @@ offTheme();
 await Desktop.print.page();                  // системный диалог печати текущего окна
 await Desktop.print.html('<h1>Отчёт</h1>');  // печать HTML из скрытого окна
 await Desktop.print.pdf(html, {path: '/tmp/отчёт.pdf'});   // PDF без диалога (или с ним, без path)
-await Desktop.app.path('userData');                       // каталог настроек приложения
+const userData = Desktop.app.path('userData');            // каталог настроек приложения, сразу
 await Desktop.app.info();                                 // {name, version, locale, isPackaged}
+const app = Desktop.app.get();                            // сырой `app` — только в main-процессе
+Desktop.app.quit();                                       // выход: тот же, что у пункта меню «Выход»
+Desktop.app.restart();                                    // перезапуск процесса (состояние не переносится)
 const {canceled, filePaths} = await Desktop.dialog.open({properties: ['openFile']});
 await Desktop.dialog.save({defaultPath: '/tmp/отчёт.pdf'});
 await Desktop.dialog.message({type: 'question', message: 'Продолжить?'});
@@ -419,8 +429,10 @@ window.chui.desktop.clipboard.readText();   // то же, что Desktop из re
 window.chui.desktop.recent.list();
 window.chui.desktop.progress.set(0.4);
 const off = window.chui.desktop.shortcuts.on('Mod+Shift+P', () => {});
-await window.chui.desktop.app.path('userData');            // путь приложения — по IPC, потому асинхронно
+window.chui.desktop.app.path('userData');                  // путь приложения — сразу, без промиса
 await window.chui.desktop.app.info();                      // {name, version, locale, isPackaged}
+window.chui.desktop.app.quit();                            // закрыть всё приложение (окно — window.chui.window)
+window.chui.desktop.app.restart();                         // перезапустить приложение (тоже без промиса)
 const res = await window.chui.desktop.dialog.open({properties: ['openFile']});
 await window.chui.desktop.dialog.message({type: 'question', message: 'Продолжить?'});
 await window.chui.desktop.session.clearCache();
@@ -644,7 +656,7 @@ DOM-элемент, поэтому внутри `Page.add(...)`, `Card.add(...)`
 [Константы и статические фабрики](docs/topics/constants.html), [Сценарии целиком](docs/topics/scenarios.html),
 [Витрина компонентов](docs/topics/showcase.html).
 
-Модули и десктоп-сервисы (`Main`, `App`, `I18n`, `Theme`, `Desktop`, `Log`) описаны выше, в разделе «Модули».
+Модули и десктоп-сервисы (`Main`, `I18n`, `Theme`, `Desktop`, `Log`) описаны выше, в разделе «Модули».
 
 ### В разработке
 

package/framework/appLayout/default/chui_app_layout.js

@@ -89,19 +89,12 @@ class Route extends Events {
         //
         setPageName(page.getTitle());
         center.innerHTML = '';
-        const page_node = page.render();
-        // Заголовок страницы — в содержимом, первым блоком (вид — `page_title` в
-        // chui_page/styles.css). Текст идёт текстовым узлом, а не разметкой: имя
-        // страницы приходит от приложения и могло бы принести теги
-        const title = page.getTitle();
-        if (title !== undefined && title !== null && String(title) !== "") {
-            const block = document.createElement("page_title");
-            const icon = page.getIcon();
-            if (icon !== undefined && icon !== null) block.innerHTML = String(icon);
-            block.appendChild(document.createTextNode(String(title)));
-            page_node.prepend(block);
-        }
-        center.appendChild(page_node);
+        // Содержимое собирает сама страница (`Page#render`), оболочка в него не подмешивает
+        // ничего: узел `page_title` (был здесь) дублировал заголовок, который страница
+        // рисует сама, а `Page#render` отдаёт один и тот же узел — повторный переход на тот
+        // же экземпляр страницы (кнопка «Назад» из `Page#setBackButton`) добавлял второй
+        // заголовок. Место названия — шапка (`setPageName`).
+        center.appendChild(page.render());
         const _page = center.querySelector('page');
         new Animation(_page).fadeIn();
         // Стирания `center.removeAttribute("style")` здесь больше нет: инлайновых

package/framework/appLayout/default/global_style.css

@@ -884,11 +884,14 @@ app_menu_empty {
    ниже содержимого, и длинное название выдавило бы кнопки за край окна. Полный текст
    лежит в подсказке (её ставит setPageName в chui_app_layout.js). */
 page_name {
-    /* Название переехало в содержимое страницы (`page_title` в chui_page/styles.css):
-       в шапке оно уезжало при прокрутке и делило полосу с кнопками. Узел оставлен
-       якорем — за ним разметка ставит полосу меню (`applyPageMenuBar`), а `setPageName`
-       продолжает держать текст для меню маршрутов и подсказки */
-    display: none;
+    /* Название показывает шапка, а не содержимое: оболочка в страницу его не подмешивает
+       (`Route#go`), поэтому приложение, рисующее свой заголовок, ничего не дублирует.
+       Узел — якорь полосы меню (`applyPageMenuBar` ставит её следом), и он же держит текст
+       для меню маршрутов и подсказки (`setPageName`).
+       У страницы с меню-баром название скрыто — место занимает полоса (правило
+       `.header_with_menu_bar page_name` ниже) */
+    display: flex;
+    align-items: center;
     outline: none;
     box-sizing: border-box;
     min-width: 0;

package/framework/modules/chui_bridge/preload.js

@@ -1,5 +1,5 @@
 const {contextBridge, ipcRenderer} = require("electron");
-const {SERVICES_CHANNELS, SERVICES_CALLS, BRIDGE_CHANNELS, BRIDGE_ARGS} = require("../chui_services/chui_channels");
+const {SERVICES_CHANNELS, SERVICES_CALLS, SERVICES_SYNC_CALLS, BRIDGE_CHANNELS, BRIDGE_ARGS} = require("../chui_services/chui_channels");
 // Мост переиспользует ту же обёртку сервисов, что и страница: разница только в транспорте
 // (`Desktop` в preload'е сам вызовет ipcRenderer, потому что `window.chui` ему не виден)
 const {Desktop} = require("../chui_services/desktop");
@@ -16,8 +16,10 @@ const {Desktop} = require("../chui_services/desktop");
  * файл при `DOMContentLoaded`.
  *
  * Формы API:
- * - `window.chui.desktop.{clipboard, recent, progress, shortcuts}` — то же, что `Desktop` из
+ * - `window.chui.desktop.{app, clipboard, recent, progress, shortcuts}` — то же, что `Desktop` из
  *   `require('chuijs')`, поэтому код страницы переносится между режимами почти без правок;
+ *   `desktop.app.quit()`/`restart()` закрывают и перезапускают всё приложение, а не окно; ответ
+ *   у них значением, без промиса (синхронный канал);
  * - `window.chui.services` — плоская карта «метод → канал» (транспорт, который ищет `Desktop`);
  * - `window.chui.window` — минимизировать, развернуть, закрыть, состояние окна;
  * - `window.chui.theme` — текущая тема и подписка на её смену;
@@ -74,6 +76,12 @@ const services = {};
 for (const method of Object.keys(SERVICES_CALLS)) {
     services[method] = (...args) => call(method, ...args);
 }
+// Синхронные вызовы — отдельным циклом и через `sendSync`: на синхронный канал `invoke`
+// не отвечает, промис никогда бы не завершился. Конверт `{value}`/`{error}` разбирает
+// `Desktop.#callSync`, поэтому мост отдаёт ответ как есть — как и обычный канал
+for (const [method, channel] of Object.entries(SERVICES_SYNC_CALLS)) {
+    services[method] = (...args) => ipcRenderer.sendSync(channel, ...args);
+}
 // Событие глобальной клавиши: подписка возвращает функцию отписки
 services.onShortcut = (handler = () => {}) => {
     const listener = (_event, accelerator) => handler(accelerator);
@@ -128,8 +136,19 @@ contextBridge.exposeInMainWorld("chui", {
             openExternal: (url = String()) => Desktop.shell.openExternal(url)
         },
         app: {
+            // Путь приходит значением, без промиса (синхронный канал), а `Desktop` в preload'е
+            // идёт в него сам: `window.chui` своей же странице здесь ещё не виден
             path: (name = String()) => Desktop.app.path(name),
-            info: () => Desktop.app.info()
+            info: () => Desktop.app.info(),
+            // Сырые модули Electron странице не отдают. Методы есть для единообразия
+            // с `Desktop`, но со страницы бросают ошибку с подсказкой, что взять взамен
+            get: () => Desktop.app.get(),
+            getSession: () => Desktop.app.getSession(),
+            getWebContents: () => Desktop.app.getWebContents(),
+            // Закрытие и перезапуск — как у `Desktop` из пакета: те же шаги, что у пункта меню.
+            // Отвечают значением, а не промисом (синхронный канал), поэтому `await` не нужен
+            quit: () => Desktop.app.quit(),
+            restart: () => Desktop.app.restart()
         },
         dialog: {
             open: (options = {}) => Desktop.dialog.open(options),

package/framework/modules/chui_page/styles.css

@@ -9,29 +9,6 @@ page {
     align-items: baseline;
 }
 
-/* Заголовок страницы живёт в содержимом, а не капсулой в шапке: в полосе он уезжал
-   при прокрутке и при этом занимал место рядом с кнопками. Ставит его оболочка
-   (`Route#go`), текст и значок берёт из `Page#getTitle` / `Page#getIcon` */
-page_title {
-    display: flex;
-    align-items: center;
-    gap: 10px;
-    /* Без собственных отступов: text заголовка стоит по тому же вертикали, что и блоки
-       ниже, — иначе он выезжает на 2px вправо и левый край страницы ломается */
-    margin: 0 0 calc(10px * var(--density)) 0;
-    padding: 0;
-    font-size: var(--font_lead_size);
-    font-weight: 600;
-    color: var(--text_color);
-}
-
-page_title chui_icon {
-    color: var(--link_color);
-    /* Кегль значка — как у подписи: при 20px глиф перетягивал строку */
-    font-size: var(--font_lead_size);
-}
-
-/* Страница без заголовка не держит пустую строку */
-page_title:empty {
-    display: none;
-}
+/* Вид заголовка страницы держит шапка (`page_name` в global_style.css): оболочка
+   в содержимое ничего не подмешивает (`Route#go`), поэтому страница начинается
+   со своих блоков, а видимый заголовок рисует приложение само */

package/framework/modules/chui_services/chui_channels.js

@@ -43,8 +43,32 @@ const SERVICES_CHANNELS = {
     SHORTCUT_EVENT: "chui_shortcut",
     /** Путь приложения по имени из `APP_PATH_NAMES` */
     APP_PATH: "chui_services_app_path",
+    /**
+     * Тот же путь, но ответ приходит значением, а не промисом: канал синхронный
+     * (`ipcRenderer.sendSync`). `Desktop.app.path` ходит сюда — путь берут на старте, чтобы
+     * собрать свои пути к файлам, и ждать промис там негде. Асинхронный `APP_PATH` оставлен:
+     * карта `window.chui.services` отдаётся странице целиком, её ключи — часть API безопасного
+     * режима, и убрать один из них значило бы сломать чужой вызов.
+     */
+    APP_PATH_SYNC: "chui_services_app_path_sync",
     /** Сведения о приложении: имя, версия, язык, сборка */
     APP_INFO: "chui_services_app_info",
+    /**
+     * Закрыть и перезапустить приложение со страницы. Идут через `Main.stop()`/`restart()`:
+     * это те же шаги, что у пункта меню «Выход», — снимаются обработчики сервисов, глобальные
+     * клавиши и подписки, а не просто закрывается окно.
+     */
+    APP_QUIT: "chui_services_app_quit",
+    APP_RESTART: "chui_services_app_restart",
+    /**
+     * Те же закрытие и перезапуск, но ответ приходит значением, а не промисом: канал
+     * синхронный (`ipcRenderer.sendSync`). `Desktop.app.quit()`/`restart()` ходят сюда — выход
+     * начинается тем же `Main.stop()`/`restart()`, а страница получает ответ сразу, без `await`.
+     * Асинхронные `APP_QUIT`/`APP_RESTART` оставлены: их ключи есть в карте `window.chui.services`,
+     * а это часть API безопасного режима.
+     */
+    APP_QUIT_SYNC: "chui_services_app_quit_sync",
+    APP_RESTART_SYNC: "chui_services_app_restart_sync",
     /** Системные диалоги: окно берётся у отправителя */
     DIALOG_OPEN: "chui_services_dialog_open",
     DIALOG_SAVE: "chui_services_dialog_save",
@@ -99,6 +123,8 @@ const SERVICES_CALLS = {
     localeSet: SERVICES_CHANNELS.LOCALE_SET,
     appPath: SERVICES_CHANNELS.APP_PATH,
     appInfo: SERVICES_CHANNELS.APP_INFO,
+    appQuit: SERVICES_CHANNELS.APP_QUIT,
+    appRestart: SERVICES_CHANNELS.APP_RESTART,
     dialogOpen: SERVICES_CHANNELS.DIALOG_OPEN,
     dialogSave: SERVICES_CHANNELS.DIALOG_SAVE,
     dialogMessage: SERVICES_CHANNELS.DIALOG_MESSAGE,
@@ -107,6 +133,30 @@ const SERVICES_CALLS = {
     sessionClearStorage: SERVICES_CHANNELS.SESSION_CLEAR_STORAGE
 };
 
+/**
+ * Синхронные вызовы (`ipcRenderer.sendSync`) — те, где ответ нужен значением, а не промисом.
+ *
+ * Отдельный map, а не строка в `SERVICES_CALLS`: тот мост превращает в методы страницы через
+ * `ipcRenderer.invoke`, а на синхронный канал invoke не отвечает — промис не завершился бы
+ * никогда, и страница молча ждала бы ответа.
+ *
+ * Ответ синхронного канала — конверт `{value}` или `{error}`: у `sendSync` нет канала для
+ * исключения, и без конверта причина отказа (имя пути вне белого списка) потерялась бы,
+ * а страница получила бы `undefined`. Разбирает конверт `Desktop.#callSync` — одинаково
+ * в обычном режиме и в безопасном.
+ *
+ * `sendSync` останавливает страницу на время ответа (main при этом свободен), поэтому
+ * синхронных вызовов должно быть мало и отвечать они обязаны мгновенно: `app.getPath` —
+ * чтение кеша Electron, без обращения к диску.
+ */
+const SERVICES_SYNC_CALLS = {
+    appPathSync: SERVICES_CHANNELS.APP_PATH_SYNC,
+    // Закрытие и перезапуск отвечают мгновенно (`setImmediate` в main откладывает выход),
+    // поэтому синхронный канал здесь так же уместен, как у пути: странице не нужен `await`
+    appQuitSync: SERVICES_CHANNELS.APP_QUIT_SYNC,
+    appRestartSync: SERVICES_CHANNELS.APP_RESTART_SYNC
+};
+
 /** Каналы моста: окно, тема и прикладные сообщения безопасного окна */
 const BRIDGE_CHANNELS = {
     WINDOW_ACTION: "chui_bridge_window_action",
@@ -128,6 +178,7 @@ const BRIDGE_ARGS = {
 
 exports.SERVICES_CHANNELS = SERVICES_CHANNELS
 exports.SERVICES_CALLS = SERVICES_CALLS
+exports.SERVICES_SYNC_CALLS = SERVICES_SYNC_CALLS
 exports.BRIDGE_CHANNELS = BRIDGE_CHANNELS
 exports.APP_PATH_NAMES = APP_PATH_NAMES
 exports.BRIDGE_ARGS = BRIDGE_ARGS

package/framework/modules/chui_services/desktop.js

@@ -1,4 +1,4 @@
-const {SERVICES_CHANNELS, SERVICES_CALLS} = require("./chui_channels");
+const {SERVICES_CHANNELS, SERVICES_CALLS, SERVICES_SYNC_CALLS, APP_PATH_NAMES} = require("./chui_channels");
 
 /**
  * Десктоп-сервисы со стороны страницы: буфер обмена, последние документы, прогресс на иконке
@@ -126,19 +126,75 @@ class Desktop {
     };
 
     /**
-     * Приложение со стороны страницы: пути и сведения. Прямого доступа к модулям Electron
-     * у страницы нет — это и есть рекомендация Electron вместо `remote`.
+     * Приложение: пути, сведения и сырые модули Electron.
+     *
+     * Странице модули main не отдают — это и есть рекомендация Electron вместо `remote`,
+     * поэтому пути и сведения идут по IPC. В main-процессе IPC нет, и те же методы отвечают
+     * значением: `path()` берёт путь у Electron, а `get()`/`getSession()`/`getWebContents()`
+     * отдают сами объекты.
      *
      * ```javascript
-     * await Desktop.app.path('userData');   // каталог настроек приложения
-     * await Desktop.app.info();             // {name, version, locale, isPackaged}
+     * const dir = Desktop.app.path('userData');   // путь приходит сразу, без промиса
+     * const info = await Desktop.app.info();      // {name, version, locale, isPackaged}
+     * Desktop.app.quit();                         // закрыть приложение — тоже без промиса
      * ```
      */
     static app = {
-        /** Путь по имени из белого списка (`"userData"`, `"downloads"`, …) */
-        path: (name = String()) => Desktop.#call("appPath", String(name)),
+        /**
+         * Путь по имени из белого списка (`"userData"`, `"downloads"`, …).
+         *
+         * Отвечает значением, а не промисом: из этих путей страница собирает свои (файлы,
+         * логи, кеш) на старте, и `await` пришлось бы протаскивать через весь код инициализации.
+         * Идёт по синхронному каналу (`SERVICES_SYNC_CALLS`), а потому значение берётся один раз
+         * на имя и кешируется — `sendSync` останавливает страницу на время ответа, а путь за
+         * жизнь приложения не меняется (`app.setPath` в main — редкий случай, и тогда кеш
+         * страницы устареет так же, как устарел бы вызов, сделанный раньше).
+         * Прежний `await Desktop.app.path(...)` продолжает работать: `await` на строке
+         * возвращает ту же строку.
+         *
+         * Работает и в main-процессе: там канала нет, и путь берётся у Electron напрямую
+         * (с тем же белым списком), поэтому `main.js` обходится без отдельного класса путей.
+         */
+        path: (name = String()) => Desktop.#appPath(String(name)),
         /** @returns {Promise<{name: string, version: string, locale: string, systemLocale: string, isPackaged: boolean}>} */
-        info: () => Desktop.#call("appInfo")
+        info: () => Desktop.#call("appInfo"),
+        /**
+         * Сырой объект `app` Electron. **Только для main-процесса:** странице модули main
+         * не отдают, и здесь она получит ошибку с подсказкой — вместо `app` со страницы берут
+         * `Desktop.app.info()`, `Desktop.session.*`, `Desktop.dialog` или свой канал.
+         *
+         * ```javascript
+         * const app = Desktop.app.get();                  // main.js
+         * app.on('session-created', (session) => {});
+         * ```
+         */
+        get: () => Desktop.#electronObject("app"),
+        /** Сырой `session` Electron (только main-процесс; странице — `Desktop.session.*`) */
+        getSession: () => Desktop.#electronObject("session"),
+        /** Сырой `webContents` Electron (только main-процесс) */
+        getWebContents: () => Desktop.#electronObject("webContents"),
+        /**
+         * Закрыть приложение: тот же выход, что у пункта меню «Выход» — `Main.stop()` снимает
+         * обработчики сервисов, глобальные клавиши и подписки, а затем приложение выходит.
+         *
+         * Отвечает значением, а не промисом (синхронный канал): ждать результат не нужно и
+         * `await` ничего не меняет — `await true` даёт то же `true`. Ответ приходит до выхода,
+         * потому что main откладывает `stop()` через `setImmediate`.
+         *
+         * ```javascript
+         * new Button({title: 'Выход', clickEvent: () => Desktop.app.quit()});
+         * ```
+         * @returns {boolean} `true` — выход начат
+         */
+        quit: () => Desktop.#callSync("appQuitSync"),
+        /**
+         * Перезапустить приложение: процесс поднимается заново (`Main.restart()` →
+         * `app.relaunch()`), поэтому состояние из памяти не переносится — сохраните его сами.
+         *
+         * Отвечает значением, а не промисом (синхронный канал), как и `quit()`.
+         * @returns {boolean} `true` — перезапуск начат
+         */
+        restart: () => Desktop.#callSync("appRestartSync")
     };
 
     /**
@@ -183,6 +239,9 @@ class Desktop {
     static #history_handlers = new Set();
     static #history_event_bound = false;
     static #history_bridge_unsubscribe = undefined;
+    // Пути приложения, уже полученные значением: `sendSync` останавливает страницу на время
+    // ответа, поэтому за одним и тем же именем в main ходят один раз
+    static #app_paths = new Map();
 
     static #bridge() {
         if (typeof window === "undefined" || window.chui === undefined) return undefined;
@@ -197,6 +256,65 @@ class Desktop {
         return ipcRenderer.invoke(SERVICES_CALLS[method], ...args);
     }
 
+    /**
+     * Синхронный вызов сервиса: в безопасном режиме — метод моста, иначе — канал `sendSync`.
+     * Канал отвечает конвертом `{value}`/`{error}` (см. `SERVICES_SYNC_CALLS` в chui_channels.js),
+     * поэтому исключение из main превращается здесь в обычную ошибку с его текстом.
+     */
+    static #callSync(method = String(), ...args) {
+        const services = Desktop.#bridge();
+        const answer = services !== undefined && typeof services[method] === "function"
+            ? services[method](...args)
+            : require("electron").ipcRenderer.sendSync(SERVICES_SYNC_CALLS[method], ...args);
+        if (answer === null || typeof answer !== "object") return answer;
+        if (answer.error !== undefined) throw new Error(answer.error);
+        return answer.value;
+    }
+
+    /**
+     * Путь приложения значением (см. `Desktop.app.path`).
+     *
+     * В main-процессе IPC недоступен (`ipcRenderer` там нет, а отправителя-страницы не
+     * существует), поэтому путь берётся у Electron напрямую — с той же проверкой белого
+     * списка, что и в канале. Это позволяет звать `Desktop.app.path()` из `main.js` и со
+     * страницы одним и тем же вызовом.
+     */
+    static #appPath(name = String()) {
+        if (Desktop.#app_paths.has(name)) return Desktop.#app_paths.get(name);
+        const value = Desktop.#inMainProcess()
+            ? Desktop.#appPathInMain(name)
+            : Desktop.#callSync("appPathSync", name);
+        Desktop.#app_paths.set(name, value);
+        return value;
+    }
+
+    /** Различает процессы: у main нет `window`, у страницы и preload'а — есть */
+    static #inMainProcess() {
+        return typeof window === "undefined";
+    }
+
+    /** main-процесс: путь у Electron напрямую, но только из белого списка */
+    static #appPathInMain(name = String()) {
+        if (APP_PATH_NAMES.includes(name) === false) {
+            throw new Error(`Desktop.app.path: имя «${name}» вне белого списка`);
+        }
+        return require("electron").app.getPath(name);
+    }
+
+    /**
+     * Сырой объект Electron для main-процесса.
+     *
+     * Со страницы `app`/`session`/`webContents` недоступны: Electron не рекомендует `remote`,
+     * а мост preload'а отдаёт только узкий `window.chui`. Поэтому вместо тихого `undefined`
+     * здесь ошибка с подсказкой, что взять взамен.
+     */
+    static #electronObject(name = String()) {
+        if (Desktop.#inMainProcess() === false) {
+            throw new Error(`Desktop.app: сырой «${name}» доступен только в main-процессе — со страницы возьмите Desktop.app.info(), Desktop.session.* или свой канал из security.channels`);
+        }
+        return require("electron")[name];
+    }
+
     static #subscribe(accelerator = String(), handler = () => {}) {
         const handlers = Desktop.#shortcut_handlers.get(accelerator) ?? new Set();
         const first = handlers.size === 0;

package/index.js

@@ -155,6 +155,18 @@ function inRenderer() {
     return process !== undefined && process.type === "renderer";
 }
 
+/**
+ * Путь приложения по имени из белого списка.
+ *
+ * Одно правило на два канала (`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;
 
@@ -233,6 +245,9 @@ class Main {
     // Десктоп-сервисы (буфер, недавние, прогресс, глобальные клавиши) и их подписки по окнам
     #services_enabled = false;
     #service_handlers = [];
+    // Синхронные каналы снимаются не `removeHandler`, а `removeListener`: они зарегистрированы
+    // через `ipcMain.on` — см. `#handleSync`
+    #service_sync_handlers = [];
     #shortcut_subscribers = new Map();
     #shortcut_watchers = new Map();
     #progress_windows = new Map();
@@ -695,10 +710,11 @@ class Main {
         });
         // Приложение и системные диалоги для страницы: Electron советует IPC вместо `remote`.
         // Путь — только из белого списка, диалог и сессия — у окна-отправителя.
-        this.#handle(SERVICES_CHANNELS.APP_PATH, (event, name) => {
-            if (APP_PATH_NAMES.includes(name) === false) throw new Error(`App.path: имя «${name}» вне белого списка`);
-            return app.getPath(name);
-        });
+        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(),
@@ -706,6 +722,31 @@ class Main {
             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));
@@ -767,6 +808,25 @@ class Main {
         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.#service_sync_handlers.push([channel, listener]);
+        return this;
+    }
+
     /**
      * Включает мост безопасных окон (`contextBridge`): управление окном, тема и прикладные
      * сообщения по белому списку каналов. Вызывается сам при создании безопасного окна.
@@ -1051,6 +1111,8 @@ class Main {
         // Десктоп-сервисы: снимаем обработчики IPC, подписки клавиш и сами клавиши
         for (const [channel] of this.#service_handlers) ipcMain.removeHandler(channel);
         this.#service_handlers = [];
+        for (const [channel, listener] of this.#service_sync_handlers) ipcMain.removeListener(channel, listener);
+        this.#service_sync_handlers = [];
         this.#shortcut_subscribers.clear();
         this.#shortcut_watchers.clear();
         this.#progress_windows.clear();
@@ -1210,44 +1272,6 @@ class Styles {
     };
 }
 
-class Application {
-    getApp() {
-        if (inRenderer()) throw new Error("App.get(): странице не отдают модули main — возьмите Desktop.app.path()/info() или свой канал из security.channels");
-        return app;
-    }
-    getSession() {
-        if (inRenderer()) throw new Error("App.getSession(): странице не отдают сессию main — возьмите Desktop.session.*");
-        return session;
-    }
-    getWebContents() {
-        if (inRenderer()) throw new Error("App.getWebContents(): странице не отдают webContents main — действия идут через Desktop или свой канал из security.channels");
-        return webContents;
-    }
-}
-
-class App {
-    static get() { return new Application().getApp() }
-    static getSession() { return new Application().getSession() }
-    static getWebContents() { return new Application().getWebContents() }
-    // ПУТИ
-    static homePath() { return new Application().getApp().getPath("home") }
-    static appDataPath() { return new Application().getApp().getPath("appData") }
-    static userDataPath() { return new Application().getApp().getPath("userData") }
-    static sessionDataPath() { return new Application().getApp().getPath("sessionData") }
-    static logsPath() { return new Application().getApp().getPath("logs") }
-    static tempPath() { return new Application().getApp().getPath("temp") }
-    static exePath() { return new Application().getApp().getPath("exe") }
-    static modulePath() { return new Application().getApp().getPath("module") }
-    static desktopPath() { return new Application().getApp().getPath("desktop") }
-    static documentsPath() { return new Application().getApp().getPath("documents") }
-    static downloadsPath() { return new Application().getApp().getPath("downloads") }
-    static musicPath() { return new Application().getApp().getPath("music") }
-    static picturesPath() { return new Application().getApp().getPath("pictures") }
-    static videosPath() { return new Application().getApp().getPath("videos") }
-    static recentPath() { return new Application().getApp().getPath("recent") }
-    static crashDumpsPath() { return new Application().getApp().getPath("crashDumps") }
-}
-
 module.exports = {
     Main: Main,
     sleep: sleep,
@@ -1405,8 +1429,6 @@ module.exports = {
     transliterate: transliterate,
     store: store,
     //
-    App: App,
-    //
     // Десктоп-сервисы: классы main-процесса и доступ из страницы
     Shortcuts: Shortcuts,
     Shell: Shell,

package/package.json

@@ -2,7 +2,7 @@
   "name": "chuijs",
   "productName": "chuijs",
   "description": "component framework chUiJS",
-  "version": "4.0.1",
+  "version": "4.0.2",
   "private": false,
   "main": "index.js",
   "type": "commonjs",