chuijs 4.0.2 → 4.0.4

package/README.md

@@ -1,672 +1,71 @@
 # chuijs
-### CHROME_SANDBOX FIX
-### CHROME\_SANDBOX FIX 1
-```shell
-cd node_modules/electron/dist && sudo chown root chrome-sandbox && sudo chmod 4755 chrome-sandbox
-```
-### Структура
-#### exampleApp / app / views / main.js
-```javascript
-const { Page, Button, TextInput, Notification, Log } = require('chuijs');
-class MainPage extends Page {
-    constructor() {
-        super();
-        this.setTitle('Сказать привет!');
-        this.setMain(false)
-
-        let name = new TextInput({
-            title: 'Введите ваше имя',
-            placeholder: 'Введите ваше имя',
-            required: false
-        });
-        let hello = new Button({
-            title: "Сказать привет!",
-            clickEvent: () => {
-                if (name.getValue() !== "") {
-                    new Notification({
-                        title: `Привет, ${name.getValue()}!`, text: `Привет, ${name.getValue()}!`,
-                        style: Notification.STYLE.SUCCESS, showTime: 5000
-                    }).show();
-                } else {
-                    new Notification({
-                        title: `Привет мир!`, text: `Привет мир!`,
-                        style: Notification.STYLE.SUCCESS, showTime: 5000
-                    }).show();
-                }
-            }
-        })
-        this.add(name, hello)
-    }
-}
-exports.MainPage = MainPage
-```
-#### exampleApp / app / app.js
-```javascript
-/** RENDERER ПРОЦЕСС */
-/** ИМПОРТЫ */
-const { AppLayout, render, Log } = require('chuijs');
-/** СТРАНИЦЫ */
-const { MainPage } = require('../app/views/main');
-class App extends AppLayout {
-    constructor() {
-        super();
-        /** РОУТЫ */
-        this.setRoute(new MainPage());
-    }
-}
-render(() => new App()).catch(err => Log.error(err))
-```
-`render(callback)` возвращает `Promise`, который резолвится после `DOMContentLoaded` (или сразу, если документ уже загружен) результатом `callback` и реджектится его ошибкой.
-#### exampleApp / main.js
-```javascript
-/** main.js */
-const { Main, MenuItem, path, Desktop } = require('chuijs');
-const main = new Main({
-    name: "exampleApp",
-    // размеры окна задаются вложенным объектом sizes
-    sizes: {
-        width: 1366,
-        height: 768,
-        minWidth: 960,
-        minHeight: 540
-    },
-    render: `${__dirname}/app/app.js`,
-    devTools: false,
-    resizable: true,
-    // папка загрузок: если не задана, путь выбирает Electron
-    paths: {
-        downloadPath: path.join(Desktop.app.path("userData"), "downloads")
-    }
-    /** icon: `${__dirname}/resources/icons/app/icon.png` */
-});
-main.start({
-    hideOnClose: false,
-    tray: [
-        new MenuItem().help(`exampleApp`),
-        new MenuItem().button('Консоль разработчика', () => main.toggleDevTools()),
-        new MenuItem().separator(),
-        new MenuItem().quit("Выход")
-    ]
-})
-```
-
-> `Main` — обычный класс, а не singleton: конструктор только сохраняет опции
-> и настраивает `app.commandLine`. Окно создаётся в `start()` (внутри `app.whenReady()`),
-> поэтому окно доступно через `main.getWindow()` только после старта.
-#### Download Session в main.js
-```javascript
-const { Desktop } = require('chuijs');
-const app = Desktop.app.get();      // сырой `app` — только в main-процессе
-app.on('session-created', (session) => {
-    session.on('will-download', (e, item, contents) => {
-        // ...
-    });
-});
-```
-#### TelegramBot API
-```javascript
-const { TelegramBot } = require('chuijs');
-let bot = new TelegramBot("token");
-bot.setToken("token");
-
-// Функции
-async function run() {
-    await bot.getMe();
-    await bot.getUpdates();
-    await bot.getChat("id");
-    /* ... */
-}
-```
-### Модули
-
-Инфраструктура и утилиты из корня пакета: `const { Main, MenuItem, Log, path } = require('chuijs');`
-
-#### `Main`
-Создаёт окно, трей и управляет жизненным циклом приложения.
-
-```javascript
-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(Desktop.app.path('userData'), 'downloads') }
-});
-main.start({ hideOnClose: false, tray: [new MenuItem().quit('Выход')] });
-```
 
-Опции конструктора: `name`, `sizes {width, height, minWidth, minHeight}`, `render`, `devTools`,
-`webSecurity`, `resizable`, `security {contextIsolation, csp, channels}`, `paths {downloadPath}`, `icon`.
-Если `icon` не передан, `Main` сам подставляет иконку приложения по умолчанию.
-`security` включает безопасный режим окна (см. «Безопасный режим (preload + contextBridge + CSP)»),
-по умолчанию режим прежний — Node в рендерере.
-`paths.downloadPath` — папка загрузок: если она задана, `Main` подписывается на `will-download`
-сессии и сохраняет файлы туда (папка создаётся при необходимости, существующий файл не перезаписывается).
-Без опции Electron выбирает путь сам, как и раньше.
-`start()` принимает `{hideOnClose, globalMenu, tray, extensions}` и создаёт окно внутри `app.whenReady()`.
-API: `getWindow(name?)`, `getMainWindow()`, `getWindows()`, `createWindow(options)`, `focusWindow(name)`,
-`closeWindow(name)`, `sendTo(name, channel, ...args)`, `toggleDevTools(name?)`, `enableServices()`,
-`stop()`, `restart()`, `enableAutoUpdateApp(start)`, `sendDownload(title, body, windowName?)`,
-`sendDownloadUpdate(...)`, `sendDownloadComplete(...)`, `sendDownloadError(...)`.
-
-**Мультиоконность.** Главное окно регистрируется под именем `Main.MAIN_WINDOW` (`'main'`),
-а дополнительные создаёт `createWindow()`: возвращает `BrowserWindow` и вызывается с `await`,
-потому что окно можно создать только после `app.whenReady()`. У каждого окна свой скрипт
-рендерера (`render`) и свой документ, поэтому `AppLayout` каждого окна ведёт свои узлы в
-`chui_layout` (см. «Разметка и `chui_layout`») — окна не мешают друг другу.
-
-```javascript
-const preview = await main.createWindow({
-    name: 'preview',
-    title: 'Просмотр',
-    sizes: { width: 900, height: 600 },
-    render: `${__dirname}/app/preview.js`,
-    hideOnClose: true
-});
-main.sendTo('preview', 'preview_update', payload);   // сообщение в конкретное окно
-main.focusWindow('preview');
-main.closeWindow('preview');                          // закрывает окно, не приложение
-main.getWindows();                                    // [{name, window}, …]
-```
-
-Закрытие окна снимает его подписки на глобальные клавиши и освобождает комбинации,
-которые больше никто не слушает.
-
-`enableAutoUpdateApp(start)` — задержка перед первой проверкой обновления в миллисекундах;
-подписки апдейтера и подтверждение установки ставятся один раз на экземпляр `Main`.
-`stop()` и `restart()` снимают свои обработчики: IPC (`show_system_notification`, `SEND_LOG_TEXT`,
-`updateInstallConfirm`), обработчики десктоп-сервисов вместе с глобальными клавишами,
-подписку апдейтера и глобальные обработчики ошибок процессов —
-повторный `start()` подпишет их заново по одному разу. Со страницы то же делают
-`Desktop.app.quit()` и `Desktop.app.restart()`: страница — код самого приложения, поэтому своей
-кнопке «Выход» не нужен отдельный канал в каждом проекте. Оба отвечают значением, а не промисом
-(синхронный канал, как у `Desktop.app.path`), поэтому `await` не обязателен.
-
-Пути приложения отдаёт `Desktop.app.path(name)` — и в main-процессе, и на странице, значением
-без промиса (на странице — синхронным каналом, в main — прямо у Electron):
-
-```javascript
-const { Desktop } = require('chuijs');
-Desktop.app.path('userData');     // .../AppData/<name>
-Desktop.app.path('downloads');
-Desktop.app.path('logs');
-```
-
-Имена берутся из белого списка: `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 = Desktop.app.get();                   // main.js
-app.on('session-created', (session) => { /* … */ });
-```
-
-Со страницы эти методы бросают ошибку с подсказкой: вместо них берут `Desktop.session.*`,
-`Desktop.dialog` или свой канал из `security.channels`.
-
-#### `Log`
-Пишет в `userData/logs/app_<date>.log`.
-
-```javascript
-Log.info('сообщение');
-Log.error(new Error('что-то пошло не так'));
-```
-
-Из renderer-процесса вызов уходит в main через `ipcRenderer.send("SEND_LOG_TEXT", ...)`.
-
-Необработанные исключения и необработанные reject’ы промисов тоже попадают в этот лог:
-в main — `process.on("uncaughtException"/"unhandledRejection")`, в renderer —
-`window`-события `error` и `unhandledrejection`. Приложение при этом продолжает работу
-(обработчики снимаются в `Main.stop()`/`restart()`).
-
-#### `sleep`, `render`, `formatBytes`
-Утилиты из `chui_functions`.
-
-```javascript
-await sleep(1000);                              // пауза, мс
-render(() => new App()).catch(err => Log.error(err));  // точка входа renderer
-formatBytes(1536);                              // "1.5 KiB"
-```
-
-`render(callback)` ждёт `DOMContentLoaded` и резолвится результатом `callback`.
-
-#### Шрифты
-`AppLayout` сам подключает базовую группу (текстовый `chui_I` + иконки `chui_mir`) — это ~1.5 МБ
-CSS из 3.67 МБ всех шрифтов. Моноширинный `chui_mono` (~2.2 МБ) вставляется по требованию:
-его вызывает `TextEditor`, а в своём CSS можно запросить явно:
-
-```javascript
-require('chuijs/framework/modules/chui_fonts').installMono();
-```
-
-Повторные вызовы `install()`/`installMono()` бесплатны: если стиль уже в документе,
-он не собирается заново.
-
-#### Иконка приложения по умолчанию
-`getDefaultIcon()` объявлена во внутреннем модуле `framework/modules/chui_functions` и
-**наружу не реэкспортируется**: `require('chuijs').getDefaultIcon` — это `undefined`.
-`Main` вызывает её сам, если опция `icon` не задана (на macOS результат дополнительно
-прогоняется через `Main.#resizeIconTray()`). Свой путь задаётся опцией `icon`:
-
-```javascript
-new Main({ name: 'app', icon: `${__dirname}/resources/icon.png` });
-```
-
-#### `MenuItem`
-Пункты меню трея и глобального меню (цепочка из 45 методов: `button`, `submenu`, `radio`,
-`checkbox`, `help`, `quit`, `appMenu`, `fileMenu`, `editMenu`, `viewMenu`, `windowMenu` и др.).
-
-```javascript
-new MenuItem().help('exampleApp');
-new MenuItem().button('Консоль разработчика', () => main.toggleDevTools());
-new MenuItem().separator();
-new MenuItem().submenu('Ещё', [new MenuItem().quit('Выход')]);
-new MenuItem().quit('Выход');
-```
+Компонентный фреймворк для Electron: интерфейс, десктоп-сервисы, локализация и доступность.
+Около 140 компонентов — от кнопок и полей ввода до сетки данных, диаграммы Ганта и расписания —
+плюс инфраструктура: окна и трей, IPC-мост, темы, словари, журнал, валидация.
 
-#### `TelegramBot`
-Обёртка над Telegram Bot HTTP API (26 методов).
+## Установка
 
-```javascript
-const bot = new TelegramBot('token');
-bot.setToken('token');
-await bot.getMe();
-await bot.sendMessage({ chat_id: '123', text: 'привет' });
+```shell
+npm install chuijs
 ```
 
-#### Десктоп-сервисы
-Сервисы системы живут в main-процессе (`globalShortcut`, `clipboard`, `app.addRecentDocument`
-доступны только там), а страница работает с ними через `Desktop`: он сам выбирает транспорт —
-канал `ipcRenderer.invoke` в обычном режиме или методы `window.chui.services` (preload +
-`contextBridge`) в безопасном. Имена каналов лежат в одном модуле `chui_services/chui_channels`,
-поэтому main и рендерер не расходятся. Пути приложения — единственное исключение: они идут
-синхронным каналом (`Desktop.app.path` отвечает значением, а не промисом, см. ниже).
-
-```javascript
-const { Desktop } = require('chuijs');
-await Desktop.clipboard.writeText('привет');
-await Desktop.clipboard.readText();          // 'привет'
-await Desktop.clipboard.readImage();         // data URL или undefined
-await Desktop.recent.add('/path/report.pdf', 'report.pdf');
-await Desktop.recent.list();                 // [{path, name}] — своя история, см. ниже
-await Desktop.progress.set(0.4);             // 40% на иконке приложения (панель задач, док)
-Desktop.progress.clear();
-await Desktop.shell.openExternal('https://electronjs.org');   // ссылка — в браузере по умолчанию
-const off = Desktop.shortcuts.on('Mod+Shift+P', () => palette.open());
-off();                                       // снять подписку
-await Desktop.theme.get();                   // {theme: 'dark', source: 'light'}
-await Desktop.theme.set(Desktop.theme.SOURCE.DARK);   // 'dark' | 'light' | 'system'
-await Desktop.theme.toggle();                // светлая ↔ тёмная
-const offTheme = Desktop.theme.onChange((theme, source) => Log.info(theme));
-offTheme();
-await Desktop.print.page();                  // системный диалог печати текущего окна
-await Desktop.print.html('<h1>Отчёт</h1>');  // печать HTML из скрытого окна
-await Desktop.print.pdf(html, {path: '/tmp/отчёт.pdf'});   // PDF без диалога (или с ним, без path)
-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: 'Продолжить?'});
-await Desktop.session.clearCache();                       // кеш своей сессии
-await Desktop.session.clearStorageData({storages: ['cookies']});
-```
+Electron ставится в само приложение, фреймворк лишь использует его. Если под Linux Electron не
+запускается из-за песочницы Chromium — нужен разовый шаг с `chrome-sandbox`, он описан в разделе
+[«Начало работы»](docs/guide/start.html).
 
-Глобальная клавиша регистрируется в main один раз на комбинацию: сколько бы окон ни подписалось,
-`globalShortcut.register` вызывается один раз, событие уходит только окнам-подписчикам, а закрытие
-окна освобождает комбинации, которые больше никто не слушает.
+## Быстрый старт
 
-Main-сторона (для кода в `main.js`, без страницы):
+`main.js` — окно и трей:
 
 ```javascript
-const { Shortcuts, Shell, Clipboard, RecentDocuments, TaskbarProgress, Theme, Print } = require('chuijs');
-const shortcuts = new Shortcuts();
-shortcuts.register('Mod+Shift+P', () => main.focusWindow('preview'));  // false — комбинацию занял другой процесс
-shortcuts.isRegistered('Mod+Shift+P');
-shortcuts.destroy();                        // снять клавиши и подписку на will-quit
-
-const clipboard = new Clipboard();
-clipboard.writeText('привет');
-
-const shell = new Shell();
-shell.openExternal('https://electronjs.org');   // false — схема не разрешена
-Shell.isExternal('file:///etc/passwd');         // false: чужие схемы не открываются
-
-const recent = new RecentDocuments({ limit: 5 });
-recent.add('/path/report.pdf', 'report.pdf');
-recent.menuItem();                          // {role: 'recentDocuments', submenu: [{role: 'clearRecentDocuments'}]}
-
-const progress = new TaskbarProgress(main.getWindow());
-progress.set(0.4);
-progress.setError();
-progress.clear();
-
-const printed = new Print();
-printed.pdf('<h1>Отчёт</h1>', {path: '/tmp/отчёт.pdf'});   // без path откроется диалог сохранения
-// прогресс загрузки на иконку приложения:
-// session.on('will-download', (e, item) => TaskbarProgress.trackDownload(item, win));
-```
+const { Main, MenuItem, Desktop, path } = require("chuijs");
 
-`main.enableServices()` вызывается сам из `start()`/`createWindow()`, регистрирует обработчики IPC
-и создаёт сервисы; повторный вызов ничего не делает, а `stop()`/`restart()` снимают обработчики
-вместе с глобальными клавишами. Сервисы доступны и как `main.services.{shortcuts, clipboard,
-recent, progress, theme}`.
-
-**Тема (`Desktop.theme`).** Палитры разложены по `@media (prefers-color-scheme)`, поэтому смена
-`nativeTheme.themeSource` перекрашивает интерфейс во всех окнах без правок в DOM. Источник
-(`'system'`, `'light'`, `'dark'`) хранится в настройках приложения (`electron-store`) и
-применяется при запуске — до создания окна, поэтому вспышки системной палитры нет. Подписка
-`onChange(listener)` отдаёт фактическую тему при её смене — как системой, так и пользователем.
-В main-процессе тот же сервис доступен как `main.services.theme` или отдельным классом:
-
-```javascript
-const theme = new Theme(store);
-theme.get();          // 'light' | 'dark' — фактическая тема
-theme.getSource();    // 'system' | 'light' | 'dark' — выбор
-theme.set('dark');
-theme.toggle();
-theme.restore();      // применить сохранённый выбор при старте
-```
-
-Границы возможностей Electron: `RecentDocuments` ведёт свою историю (у Electron есть только
-`app.addRecentDocument()` и `app.clearRecentDocuments()`, прочитать системный список нельзя),
-`TaskbarProgress` помнит последнее значение сам (геттера прогресса нет), а `Shortcuts.register()`
-до `app.whenReady()` бросает исключение вместо тихой ошибки. `Shell.openExternal()` открывает
-только `http:`, `https:` и `mailto:` — так страница не сможет запустить локальный файл или
-произвольную команду.
-
-#### Безопасный режим (preload + `contextBridge` + CSP)
-По умолчанию всё работает как раньше: в рендерер выдаётся Node (`nodeIntegration`), и компоненты
-фреймворка живут в странице. Если окно показывает недоверенное содержимое, его можно открыть
-без Node — опцией `security`:
-
-```javascript
 const main = new Main({
-    name: 'exampleApp',
+    name: "exampleApp",
+    sizes: { width: 1366, height: 768, minWidth: 960, minHeight: 540 },
     render: `${__dirname}/app/app.js`,
-    // Строгий режим: contextIsolation + preload-мост + CSP вместо Node в рендерере
-    security: { contextIsolation: true, csp: true, channels: ['preview:save'] }
+    paths: { downloadPath: path.join(Desktop.app.path("userData"), "downloads") },
 });
 
-// Или только для одного окна: main.start() остаётся в привычном режиме
-const preview = await main.createWindow({
-    name: 'preview',
-    title: 'Предпросмотр',
-    sizes: { width: 800, height: 600 },
-    render: `${__dirname}/app/preview-page.js`,   // скрипт документа, не preload
-    security: { contextIsolation: true, channels: ['preview:save'] }
-});
-```
-
-Что меняется в таком окне:
-
-- `nodeIntegration: false`, `contextIsolation: true`, `nodeIntegrationInSubFrames: false`,
-  `webviewTag: false` — `require`, `process` и `module` в странице недоступны, модули
-  main-процесса (в том числе `@electron/remote`) тоже;
-- preload'ом становится мост фреймворка (`framework/modules/chui_bridge/preload.js`),
-  а `render` — **скрипт документа**: мост подключает его как обычный `<script>` после
-  `DOMContentLoaded`. Поэтому код вроде `require('chuijs')` в таком окне не работает —
-  страница пишется на `window.chui`;
-- CSP вставляется в документ до его скриптов. `security.csp: true` — политика
-  `Main.SECURE_CSP` (`default-src 'none'; script-src 'self' file:; style-src … 'unsafe-inline';`
-  `img-src … data: blob:; connect-src 'none'`), строкой передаётся своя, `false` отключает.
-
-```javascript
-// Что видно странице
-window.chui.versions;        // {node, chrome, electron}
-window.chui.platform;
-window.chui.render;          // путь страницы, как он задан в опции render
-window.chui.desktop.clipboard.readText();   // то же, что Desktop из require('chuijs')
-window.chui.desktop.recent.list();
-window.chui.desktop.progress.set(0.4);
-const off = window.chui.desktop.shortcuts.on('Mod+Shift+P', () => {});
-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();
-window.chui.theme.get();                    // 'light' | 'dark'
-window.chui.theme.onChange((theme) => {});
-window.chui.window.minimize(); window.chui.window.toggleMaximize(); window.chui.window.close();
-window.chui.window.getState();              // {isMaximized, isMinimized, isFullScreen, isFocused}
-await window.chui.messaging.send('preview:save', payload);   // только каналы из security.channels
-window.chui.messaging.on('preview:update', (payload) => {});
-```
-
-Прикладные каналы работают в обе стороны: страница зовёт `messaging.send(channel, payload)`, а main
-подписывается через `main.onPageMessage(channel, handler)` и отвечает/пишет сам через
-`main.sendToPage(channel, payload, windowName?)`. Мост отказывается отправлять канал, которого нет
-в `security.channels`, и то же самое проверяет `messaging.on`.
-
-Ограничения: `sandbox: true` не поддерживается (мосту нужен Node в preload'е, поэтому
-`contextIsolation` без sandbox), а окно с интерфейсом на компонентах фреймворка должно остаться
-в привычном режиме — безопасный режим рассчитан на страницы, которым фреймворк не нужен
-(предпросмотр, справка, внешний HTML).
-
-#### Реэкспорт Electron и зависимостей
-Доступны прямо из пакета, без отдельного `require`:
-
-```javascript
-const { BrowserWindow, ipcMain, ipcRenderer, shell, path, fs, os, request,
-        transliterate, systemPreferences, chooseFile, store, downloadSession } = require('chuijs');
-```
-
-`chooseFile` — диалоги `showOpenDialog` / `showSaveDialog` / `showMessageBox`: со страницы они идут
-по IPC в окно, которое их вызвало (`Desktop.dialog`), а в main — напрямую `dialog` Electron.
-`store` — готовый экземпляр `new Store()`.
-
-#### Автоматическое обновление приложения
-Только AppImage и NSIS.
-
-```javascript
-main.enableAutoUpdateApp(5000);
-main.sendDownload('Обновление', 'Загрузка...');
-main.sendDownloadComplete('Обновление', 'Готово');
-main.sendDownloadError('Обновление', 'Ошибка');
-```
-
-#### Themes
-Оформление зависит от темы приложения: светлая, тёмная или системная. Палитры живут в
-`framework/appLayout/default/main_theme_style.css` (`@media (prefers-color-scheme: light)` / `dark`),
-а выбор темы хранит и применяет сервис `Theme`: он меняет `nativeTheme.themeSource`, поэтому Chromium
-перерисовывает интерфейс сам, без правок в DOM. Выбор сохраняется в настройках и возвращается при
-следующем запуске:
-
-```javascript
-await Desktop.theme.set(Desktop.theme.SOURCE.DARK);   // 'dark' | 'light' | 'system'
-await Desktop.theme.toggle();
-const off = Desktop.theme.onChange((theme) => Log.info(theme));
+main.start({ hideOnClose: false, tray: [new MenuItem().quit("Выход")] });
 ```
 
-Готовый переключатель в интерфейсе — компонент `ThemeToggle` (см. дальше), а строка для страницы
-настроек — `Settings.ThemeRow(...)`.
-
-Токены: поверхности — `--main_background`, `--header_background`, `--modal_background`, `--modal_scrim`,
-`--element_background` (контролы), `--element_background_2` (карточки и контент-блоки),
-`--element_background_hover`, `--element_background_disabled`; текст — `--text_color`, `--text_color_hover`,
-`--text_color_disabled`; акценты — `--blue_prime_background`, `--red_prime_background`, `--link_color`
-(ссылки в контенте); геометрия и тайминги — `--border_radius`, `--radius_circle`, `--control_height`
-(29px — высота кнопки и поля), компактный шаг контролов `--main_padding_sm` / `--control_padding_sm`,
-`--transition_time`.
-
-Обводка — один токен: `--border_color` (волосяные линии всей вёрстки: карточки, поля,
-разделители). Наведение на поле — `--border_color_hover` (приметнее волосяной, но тише акцента),
-фокус — акцентная рамка и кольцо `--blue_prime_background_tint`. Окно создаётся без системной
-рамки (`frame: false`), и своего края приложение
-не рисует: границу показывают рабочий стол и тень композитора. Поэтому нет ни рамки вокруг
-окна, ни отступа `body` под неё. Скруглений у окна и шапки тоже нет: углы окна всё равно
-режет композитор (замер на KWin — дуга ≈8px), а нарисованное приложением скругление читалось
-бы с ним спором. Непрозрачный `--main_background` на `html` остаётся: базовый цвет окна
-белый, и незакрашенная область дала бы белую кромку.
-
-Схема нативных частей — `color-scheme: light dark` в `:root`: палитры разложены по
-`prefers-color-scheme`, поэтому браузер рисует и родные мелочи (каретка, выделение, системные
-кнопки и крутилки полей) в той же схеме. Без этого токена они оставались светлыми в тёмной теме.
-Нативные *виджеты* компоненты скрывают сами и только у себя: индикатор календаря — `chui_date`,
-крутилку числа — `chui_number`, индикатор часов — `chui_time`, кнопку очистки поиска — поля
-поиска (`FileExplorer`, `JsonViewer`, `Transfer`), а выпадающие списки везде свои (см. `Select`).
-Правила, которые раньше были общими (`input[type=number]::-webkit-inner-spin-button`,
-`::-webkit-calendar-picker-indicator`) — «протекали» на чужие поля, поэтому теперь у каждого
-компонента они ограничены его узлом.
-
-Свои цвета — либо переопределением токенов своим `<style>` после загрузки темы (кандидат —
-конструктор своего layout), либо значениями в стилях конкретного компонента.
-
-Системные настройки (`prefers-reduced-motion`) и утилита `.chui_visually_hidden` описаны в разделе
-«Доступность».
-
-#### Разметка и `chui_layout` (scoped-ссылки)
-`framework/modules/chui_layout` — реестр частей layout'а. Общие узлы (шапка,
-`page_name`, `center`, app-меню, панель и ящик уведомлений) `AppLayout` регистрирует сам, а
-остальные модули берут их по роли через `LAYOUT_ROLE` / `findLayoutNode()` — без поиска по всему
-документу. Свои узлы компоненты держат приватными полями: `Dialog`, `Popup`, `ImagePopup`, `Tabs`,
-`Select`/`ComboBox`/`MultiComboBox`, уведомления, `Audio` (полоса управления и слайдеры эквалайзера),
-`TextEditorPanel` (редактор передаётся ссылкой, а не id).
+`app/app.js` — страница приложения:
 
 ```javascript
-const {LAYOUT_ROLE, getLayout, findLayoutNode, requireLayoutNode} = require('chuijs/framework/modules/chui_layout/chui_layout');
-
-const layout = getLayout();                       // последний созданный layout
-layout.get(LAYOUT_ROLE.CENTER);                   // узел по роли
-findLayoutNode(LAYOUT_ROLE.NOTIFICATION_BOX_MAIN, myNode);   // layout, которому принадлежит узел
-requireLayoutNode(LAYOUT_ROLE.NOTIFICATION_PANEL);           // то же, но с понятной ошибкой
-```
-
-`LayoutRefs.set(role, node)` / `.get(role)` / `.owns(node)` — узел принадлежит тому layout'у, в поддереве
-которого он находится; если узел ещё не в дереве (только что созданное уведомление), берётся последний
-созданный layout. `registerLayout(layout)` / `unregisterLayout(layout)` нужны сценариям с несколькими
-layout'ами (новое окно, тестовый стенд).
-
-Из-за этого в `framework/` не осталось поиска узлов по всему документу. Единственные оставшиеся
-`getElementById` — проверка «стиль с таким id уже подключён» в `chui_functions` и `chui_fonts`
-(у каждого окна свой документ, и это именно документная проверка), и
-`document.querySelector('script[id=...]')` в `AppLayout.setScript()` для однократного подключения скрипта.
-`getElementsByTagName` остался один раз — `Select.setDefaultOption()` перебирает опции в своём приватном
-`#dropdown`, то есть внутри собственного поддерева, а не по документу.
-
-### Локализация и RTL
-
-Строки интерфейса берутся по ключу, а не на месте: `I18n.t("common.close")`. Один ключ — один текст
-в словаре языка, поэтому подписи переводятся без правок кода компонентов.
-
-```javascript
-const { I18n, Desktop } = require('chuijs');
-
-I18n.setLocale('en');                  // 'ru' (по умолчанию) или 'en' — тексты и `lang` документа
-I18n.t('validate.max', {max: 5});      // 'Value must be at most 5'
-I18n.getLocales();                     // ['ru', 'en'] — плюс добавленные приложением
-I18n.extend('de', {'common.close': 'Schließen'});   // свой или дополненный словарь
-I18n.getDirection();                   // 'ltr' | 'rtl'
-const off = I18n.onChange((locale, direction) => render());   // пересобрать экран после смены языка
-```
-
-Словари лежат в `framework/modules/chui_i18n/locales/` по пространствам имён (один файл — одна
-группа компонентов):
-
-| Пространство | Что переводит |
-|---|---|
-| `common`, `validate`, `a11y` | общие подписи («Закрыть», «Отмена»), тексты проверок и имена элементов доступности |
-| `app_layout` | каркас окна: кнопки окна, меню, поиск, панель уведомлений, профиль, диалог обновления, а также меню «Открыть последние» и уведомления об обновлении из main-процесса |
-| `calendar` | `DateInput`, `TimeInput`, `DateTimeInput`, `DateRangeInput`, `Calendar`, `Scheduler`, `Gantt` |
-| `media` | `Audio` (включая пресеты эквалайзера), `Video` |
-| `editors` | `TextEditor`, `CodeEditor`, `MarkdownEditor`, `DiffViewer`, `JsonViewer`, `JsonEditor`, разбор JSON (`Json.errorText`) |
-| `data` | `DataGrid`, `TreeView`, `TreeTable`, `OrgChart`, `Transfer`, `FileExplorer`, `QueryBuilder` |
-| `navigation` | вкладки, меню-бар, пагинация, хлебные крошки, шаги, `SidebarNav`, `CommandPalette`, `Toolbar`, `StatusBar`, `SplitButton`, `List` |
-| `forms` | поля ввода: `Slider`, `Rating`, `ColorPicker`, `HotkeyInput`, `MaskedInput`, `OtpInput`, `Chips`, `NumberInput`, `DropZone` |
-| `feedback` | сообщения и состояния: `Alert`, `Notification`, `ToastQueue`, `Drawer`, `Spinner`, `Skeleton`, `ProgressRing`, `SlideShow`, `Avatar`, панель истории буфера, индикатор печати |
-| `graphics` | графики (`BarGraph`, `PieGraph`, `LineGraph`, `AreaGraph`, `ScatterGraph`, `Sparkline`, `RadarGraph`, `HeatmapGraph`, `Gauge` — включая подписи скрытых таблиц-альтернатив), `Kanban`, `QRCode`, `Settings`, `ThemeToggle`, `Timeline`, `PrintButton` |
-
-Незнакомый ключ отдаётся как есть, а ключ, которого нет в текущем языке, падает на резервный (`ru`) —
-интерфейс не ломается. Полноту словарей стережёт тест `test/chui_i18n_keys.test.js`: каждый
-литеральный ключ `I18n.t("...")` из кода должен быть в обоих языках, любая строка вида
-«пространство.ключ» (в том числе ключ из тернарного выражения или таблицы) тоже должна быть
-в словаре, наборы ключей `ru` и `en` обязаны совпадать, а один и тот же ключ не может быть
-объявлен дважды. Общие подписи живут в `common` и `a11y`: один и тот же текст (например,
-«Развернуть «Имя»» у дерева-таблицы и просмотра JSON) описан один раз и переводится везде сразу.
-
-**Что осталось на русском.** Служебные тексты, которые не видит пользователь: сообщения `Log`,
-исключения конструкторов о неверных опциях, демонстрационное приложение (`app/app.js`, `main.js`)
-и тестовые данные витрины (`app/views/0_maket.js`).
+const { AppLayout, Page, Button, Log, render } = require("chuijs");
 
-**Направление текста.** `I18n.setDirection('rtl')` (или локаль с `direction: 'rtl'`) ставит `dir`
-и `lang` на `<html>`; арабский (`ar`) объявляет RTL сам. Стили компонентов написаны на логических
-свойствах (`margin-inline-start`, `padding-inline`, `inset-inline-start`, `border-start-start-radius`,
-`text-align: start`), поэтому вёрстка зеркалится без отдельных RTL-правил. Физическое центрирование
-(`left: 50%` + `translate`) оставлено физическим намеренно: со сдвигом оно разъехалось бы. У элементов
-с зеркальным сдвигом (`Toggle`) есть явное правило для `[dir="rtl"]`.
-
-```javascript
-I18n.setLocale('ar');      // dir="rtl" lang="ar" — вся вёрстка зеркалится
-I18n.setDirection('rtl');  // то же без смены языка
-```
+class MainPage extends Page {
+    constructor() {
+        super();
+        this.setTitle("Сказать привет!");
+        this.add(new Button({ title: "Привет", clickEvent: () => Log.info("привет") }));
+    }
+}
 
-Локаль выбирается до сборки интерфейса: компоненты берут текст в конструкторе. Приложение может хранить
-выбор в главном процессе — `Desktop.locale.get()/set(locale)/onChange(listener)` (как `Desktop.theme`),
-значение переживает перезапуск (`electron-store`, ключ `locale`). Тот же выбор применяется и в
-main-процессе: `Locale.restore()` при старте и канал `LOCALE_SET` вызывают `I18n.setLocale()`, поэтому
-меню «Открыть последние» и уведомления об обновлении переводятся вместе с окнами.
+class App extends AppLayout {
+    constructor() {
+        super();
+        this.setRoute(new MainPage());
+    }
+}
 
-```javascript
-await Desktop.locale.set('en');                             // main сохраннит выбор
-Desktop.locale.onChange((locale) => I18n.setLocale(locale));
+render(() => new App()).catch((err) => Log.error(err));
 ```
 
-Скрипт окна подключается как preload и выполняется до документа, поэтому `dir`/`lang` ставятся ещё
-и из `AppLayout` — на настоящем документе.
-
-### Компоненты
-
-Все классы и модули интерфейса из `require('chuijs')` (таблица иконок `Icons`, константы `Styles` и
-`AcceptTypes`, а также `Desktop` — доступ к десктоп-сервисам, у него `set()` нет — описаны рядом отдельно).
-Любой компонент реализует `set()` — возвращает готовый
-DOM-элемент, поэтому внутри `Page.add(...)`, `Card.add(...)`, `ContentBlock.add(...)` передаётся
-сам объект, а в `Form.components` / `SlideShow.SLIDE` / `FieldSet.components` — тоже объекты.
-
-**Разметка `markdownText`.** Компоненты с этой опцией (`Label`, `Tooltip`, `Badge`, `Alert`,
-`Notification`, `ToastQueue`, `Chat`, `Tour`, `MarkdownEditor`) рендерят её `markdown-it` в безопасном
-режиме: сырой HTML из разметки не исполняется, а показывается текстом — так закрыт XSS через
-`markdownText`. Таблицы и `~~зачёркивание~~` поддерживаются, авто-ссылок нет: адрес становится
-ссылкой только явным `[текст](адрес)`. Обратный разбор (`htmlToMarkdown`) делает `turndown`.
-
-Описание каждого компонента — отдельная страница статического сайта документации в [`docs/`](docs/):
-[`docs/index.html`](docs/index.html) — полный индекс по группам и алфавиту, а у каждой страницы сверху
-ссылка на группу и общий список. Сайт собирается генератором `node docs/build.js`
-(`npm run docs:build`) из разметки `docs/content/*.md`, разделов этого README и скана кода
-(`framework/**`); как открыть его локально и опубликовать — в [`docs/README.md`](docs/README.md).
-Здесь — только вход в группы:
-
-- [Компоновка и навигация](docs/groups/layout-navigation.html) — 12: `AppLayout`, `Route`, `Page`, `MenuBar`, `SidebarNav`, `ContextMenu`, `CommandPalette`, `Backtop`, `Affix`, `Styles`, `Icon`, `Icons`
-- [Поля ввода](docs/groups/inputs.html) — 29: `TextInput`, `TextArea`, `NumberInput`, `Slider`, `Chips`, `DateInput`, `Select`, `ComboBox`, `MultiComboBox`, `Transfer`, `CheckBox`, `RadioGroup`, `Form`, `FieldSet` и другие
-- [Отображение](docs/groups/display.html) — 73: `Button`, `Card`, `List`, `DataGrid`, `TreeView`, `TreeTable`, `Tabs`, `Kanban`, `Gantt`, `Scheduler`, `OrgChart`, `QRCode`, `QueryBuilder`, графики и другое
-- [Окна, уведомления, медиа](docs/groups/overlays.html) — 21: `Dialog`, `Drawer`, `Popup`, `Alert`, `Notification`, `ToastQueue`, `Calendar`, `SlideShow`, `TextEditor`, `MarkdownEditor`, `Image`, `Audio`, `Video`, `WebView`, `Console`, `CustomElement`
+Дальше — [«Начало работы»](docs/guide/start.html): структура проекта, все опции `Main`, страницы
+и сервисы.
 
-Общие правила компонентов — там же: [Опции и умолчания](docs/topics/options.html),
-[Жизненный цикл `destroy()`](docs/topics/lifecycle.html), [Доступность](docs/topics/a11y.html),
-[Константы и статические фабрики](docs/topics/constants.html), [Сценарии целиком](docs/topics/scenarios.html),
-[Витрина компонентов](docs/topics/showcase.html).
+## Документация
 
-Модули и десктоп-сервисы (`Main`, `I18n`, `Theme`, `Desktop`, `Log`) описаны выше, в разделе «Модули».
+[`docs/index.html`](docs/index.html) — справочник по фреймворку: страница на каждый компонент с
+примером, составом API и заметками о доступности, а также
+[модули и сервисы](docs/modules/index.html) (`Main`, `Log`, `Desktop`, безопасный режим,
+автообновление), [локализация и RTL](docs/guide/i18n.html),
+[общие правила компонентов](docs/topics/options.html),
+[планы](docs/guide/roadmap.html) и [история изменений](docs/changelog.html).
 
-### В разработке
+## Лицензия
 
-- Нет CI: тесты (`npm test`, `node --test`) и линт есть, автоматического прогона на push нет.
-  Компоненты по-прежнему проверяются витриной `app/views/0_maket.js` и стендами Electron.
-- Локализация охватывает все словари по пространствам имён: строки интерфейса framework берутся
-  по ключу (`I18n.t`). Непереведёнными остаются служебные тексты (журнал, исключения конструкторов),
-  демонстрационное приложение `app/`, меню демо-приложения в `main.js` и данные витрины; дописать
-  словарь для нового компонента — это добавить ключи в его пространство имён.
-- RTL: вёрстка зеркалится логическими свойствами CSS; позиционирование всплывающих слоёв, которое
-  считает JavaScript (`left`/`right` в пикселях), и анимации-сдвиги пока не учитывают направление.
-  Запятые-кавычки в текстовом представлении `QueryBuilder.getText()` остались русскими «ёлочками»
-  (это текст-представление запроса, а не подпись интерфейса).
+MIT — см. [LICENSE](LICENSE).