Для разработчиков
Как собрать Problet из исходников, как устроен код, какие API видят страницы и сайты, как проверять изменения и как выпускаются сборки.
Сборка из исходников
Нужны Node.js (22 или новее) и git.
git clone https://github.com/cersat/Problet.git
cd Problet
npm install
npm start
Установочные файлы для своей системы (появятся в dist/):
npm run dist
Зависимостей во время работы нет: только Electron и electron-builder для сборки. Код — обычный JavaScript без сборщиков и транспиляции; исключение — графический редактор (см. ниже).
Устройство
Problet — приложение Electron. Главный процесс управляет окном, вкладками и данными, страницы показываются в процессах отрисовки Chromium.
| Файл | Что делает |
|---|---|
main.js | Главный процесс: окно, вкладки, навигация, меню, горячие клавиши, всплывающие окошки, IPC для всех страниц. |
index.html, renderer.js, style.css | Окно браузера: панели, вкладки, адресная строка. Открывается по адресу problet://ui/. |
vtab.js | Виртуальные вкладки: встроенные страницы без своего процесса (см. ниже). |
preload-page.js | Единственный прелоад окна и страниц: API панели, API встроенных страниц, isProblet для сайтов, заплатки для страниц расширений. |
preload-find.js, preload-popup.js, preload-error.js | Прелоады строки поиска, подсказок адресной строки и окна ошибки. |
store.js | Данные в data.json: настройки (со схемой проверки), закладки, история, сессия. |
vault.js, passcsv.js | Хранилище паролей (AES-256-GCM + scrypt) и CSV. |
adblock.js | Блокировщик: списки blocklist.txt, blocklist-paths.txt, allowlist.txt, заглушки, куки-баннеры. |
identity.js | Маскировка: User-Agent, Sec-CH-UA, Do Not Track. Список plain-ua-sites.txt. |
extensions.js, ext-shim.js | Расширения Chrome и Chrome Web Store; заплатки недостающих chrome.*. |
addons.js | Аддоны Problet: формат, разрешения, API. |
updater.js | Автообновление из релиза latest. |
headless.js | Режим без окна и управление по HTTP. |
theme.js, i18n-main.js | Тема (CSS-переменные для всех окон) и перевод главного процесса. |
cache.js, offline.js, pagetranslate.js, importer.js, calc.js, desktop.js | Кеш, страницы для офлайна, перевод страниц, импорт из браузеров, калькулятор, интеграция с системой (команда problet, ярлыки). |
pages/ | Встроенные страницы problet://: по паре имя.html + имя.js, общие common.css, i18n.js, accel.js. |
tools/ | smoke.js — сквозная проверка, paint/ — сборка графического редактора, adstub/ — заглушки рекламы. |
docs/ | Сайт проекта на GitHub Pages и эта документация. |
Вкладки: настоящие и виртуальные
Обычная вкладка — это WebContentsView со своим процессом отрисовки. Встроенные страницы так не открываются: процесс стоит 15–20 МБ, а их бывает открыто много.
Вместо этого окно браузера открыто по адресу problet://ui/, а встроенная страница — рамкой (iframe) внутри него по адресу problet://ui/<страница>/…. Для Chromium это один сайт, значит, один процесс. Вкладка получает объект VirtualView из vtab.js, который снаружи выглядит как WebContentsView: те же методы (loadURL, navigationHistory, findInPage, executeJavaScript, send…) и те же события. Поэтому остальной код главного процесса с ней работает как с обычной вкладкой.
- Пользователь видит обычные адреса
problet://settings/; перевод в адрес рамки и обратно —toFrameUrlиfromFrameUrl. - Переход со встроенной страницы на сайт меняет вид вкладки на настоящий, и наоборот. История «назад/вперёд» склеивается из кусков (
backSegs,fwdSegs). - Настоящими остаются вкладки инкогнито, вкладка с привязанной боковой панелью расширения и вкладки, которые создало расширение.
- Сообщения из рамки главный процесс узнаёт по
senderFrame(имя рамкиvt-<id>), см.vtabOfFrameиsenderTab.
API для страниц
Все API выдаёт preload-page.js через contextBridge в объекте problet. Что именно получит страница, зависит от того, где она открыта:
| Где | Что в problet |
|---|---|
Окно браузера (problet://ui/) | API панели: навигация, вкладки, адресная строка, подсказки, меню. |
Встроенные страницы problet:// | API браузера: настройки, закладки, история, пароли, загрузки, расширения, файлы и так далее. Каждый вызов — ipcRenderer.invoke, который в главном процессе проходит через handle() и проверку guard(): отвечает только встроенным страницам. |
Страницы аддонов (problet-addon://) | API аддонов (описание). |
| Скрипты аддонов на сайтах | id, lang, send, onMessage, storage — в отдельном мире скрипта. |
| Обычные сайты | window.isProblet === true и problet.isProblet === true, только когда браузер маскируется под Problet. Больше ничего. |
Проверка на сайте:
if (window.isProblet) {
// открыто в Problet
}
Как добавить встроенную страницу
- Создай
pages/имя.htmlиpages/имя.js. Подключиtheme.css,common.cssиi18n.js, как в соседних страницах. В заголовке нужна CSPdefault-src 'self'. - Добавь имя в
INTERNAL_PAGESвmain.js. - Нужен новый вызов — добавь метод в объект
probletвстроенных страниц вpreload-page.jsи обработчикhandle('канал', …)вmain.js. - Если страница переходит сама (
location.href = 'problet://…'), всё работает: переход перехватывается и становится навигацией вкладки. - Надписи пиши по-русски и добавь английский перевод в
pages/i18n-en.js.
Перевод интерфейса
Исходный язык кода — русский. Английский берётся из словаря pages/i18n-en.js: pages/i18n.js переводит встроенные страницы и окно, i18n-main.js — меню, диалоги и уведомления главного процесса. Если строки нет в словаре, она показывается по-русски. Проверка tools/smoke.js убеждается, что язык переключается на лету.
Проверки
Сквозная проверка запускает браузер в режиме без окна и проходит по настройкам, закладкам, проводнику, файлам, блокировщику, загрузкам, паролям, пространствам, аддонам, смене языка и перезапуску:
node tools/smoke.js
xvfb-run node tools/smoke.js # на Linux без дисплея
Синтаксис всех файлов проверяет и CI: node --check для *.js и pages/*.js.
Графический редактор
pages/svgedit.js — собранный scratch-paint (TurboWarp, GPL-3.0) со своей обвязкой из tools/paint/entry.jsx. Пересборка — tools/paint/build.sh (нужны git и npm). Лицензия — pages/svgedit.LICENSE.txt.
Сборки и релизы
Всё делает GitHub Actions, воркфлоу .github/workflows/build.yml:
- Проверка синтаксиса.
- Подготовка: для ветки
mainметкаlatestпереносится на новый коммит, релиз «Последняя сборка» обновляется (обычный релиз с меткой «Latest»). - Сборка на Linux, Windows и macOS параллельно; файлы выкладываются в
latestпо мере готовности, старые файлы той же системы убираются. - Отдельный релиз версии: если в версии из
package.jsonсменилось первое или второе число (нет ещё ни одного тегаv<a>.<b>.*), создаётся релизv<версия>со всеми файлами.
Сборка не запускается, если в коммите поменялись только документация (docs/, *.md) или .github/. Сайт из docs/ выкладывает отдельный воркфлоу pages.yml и только когда сайт изменился.
Ручной запуск с параметром ref (тег или коммит) собирает старую версию и выкладывает файлы в её релиз.
Версии: a.b.c в package.json. Обычное исправление — +1 к третьему числу; новая крупная возможность — ко второму (тогда появится отдельный релиз).
Стиль кода
- Отступы — табы.
- Комментарии и тексты интерфейса — по-русски, комментарий объясняет «зачем», а не «что».
- Без сборщиков и зависимостей во время работы.
- Сообщения коммитов — коротко, по-русски; версия в начале, если коммит её меняет:
9.1.2: ….
Сообщить об ошибке
Issues на GitHub. Приложи сведения со страницы problet://version (кнопка «Скопировать сведения») и, если можно, хвост журнала (где он лежит).