docs: define Gentoo HydraOS target and implementation plan

2026-10-13 03:58:07 +03:00
commit 2408d56d14
5 changed files with 284 additions and 0 deletions
@@ -0,0 +1,130 @@
+# HydraOS: минимальная графическая сессия хоста
+
+Решение первого этапа, 13 октября 2026 года. Пользователь подтвердил Gentoo,
+устанавливаемый ISO, ASUS TUF Dash F15 FX517ZC и автономную разработку.
+
+## Назначение
+
+HydraOS должна стать устанавливаемым Linux-дистрибутивом для одновременной
+работы нескольких виртуальных машин. Пользователь видит рабочий стол выбранной
+VM на весь экран и переключает машины горячими клавишами. Хост обеспечивает
+оборудование, сеть и управление VM; его графический интерфейс обычно незаметен.
+
+Подтверждённые требования: минимальная оболочка хоста по умолчанию, отсутствие
+впечатления вложенных окон, переключение клавишами, совместимость управления
+VM с другими окружениями хоста. Гостевые окружения выбираются независимо.
+Gentoo выбрана основой будущего дистрибутива. Первый этап проверяет
+графическую сессию до изготовления установочного ISO.
+
+## Решение первого этапа
+
+Предлагается labwc как композитор стандартной сессии и отдельный SPICE-просмотрщик
+для каждой VM. Панель, меню рабочего стола, оформление окон и обычные сочетания
+оконного менеджера в этой сессии не нужны. На физическом экране всегда находится
+один полноэкранный просмотрщик. Его обычный интерфейс должен быть скрыт; выбор
+USB и восстановление доступа к хосту остаются доступны по явному действию.
+
+Первый прототип рассчитан на один физический экран. Режим без рамок включает
+отсутствие всплывающей панели просмотрщика при подведении указателя к краю.
+До основной реализации отдельно проверяются два условия: сохранение
+зарезервированных клавиш хоста при захвате ввода SPICE и возможность явно
+открыть управление USB при скрытом интерфейсе просмотрщика. Если выбранный
+режим remote-viewer этого не допускает, способ управления пересматривается;
+доступность этих функций пока не считается подтверждённой.
+
+Несколько VM и их просмотрщики продолжают работать при переключении. Меняется
+видимый просмотрщик, а не питание или состояние гостя. Переключение не должно
+требовать повторной загрузки ОС или подключения к SPICE.
+
+Существующий прототип `/home/workspaces/niri-vm-lab` служит источником проверенных
+решений для виртуального оборудования и сети. Его работающие VM и диски не
+используются как тестовые объекты новой графической сессии.
+
+## Границы компонентов и совместимость
+
+- Управление VM: параметры QEMU, отдельные диски, запуск, состояние, штатное
+  выключение, приватные сокеты QMP и SPICE. Этот компонент не вызывает labwc
+  или Niri и не требует работающей графической сессии.
+- Запуск просмотрщика: подключение к выбранной VM. В обычном окружении хоста
+  просмотрщик может работать окном; графический backend определяется средой.
+- Сессия HydraOS: настройка labwc, полноэкранный показ, фокус, горячие клавиши
+  переключения и восстановление после закрытия просмотрщика.
+- Упаковка дистрибутива: ядро, драйверы, пакеты, запуск сессии, установка и
+  обновления. Это следующий самостоятельный этап после проверки оболочки.
+
+В KDE, GNOME и других окружениях хоста должны оставаться доступны общие команды
+управления и оконные просмотрщики. Специальная политика захвата клавиатуры и
+переключения полноэкранных VM гарантируется только после проверки конкретной
+сессии. Установка другой оболочки не должна менять формат профилей или дисков.
+Одновременная работа нескольких полноценных сессий хоста и передача физического
+экрана между ними в первый этап не входят.
+
+## Ввод и поведение при сбоях
+
+В стандартной сессии Meta, Alt+Tab и переключение раскладки передаются гостю.
+Для хоста резервируются Ctrl+Alt+Shift+Left/Right для смены VM и отдельное
+аварийное сочетание Ctrl+Alt+Shift+Escape для освобождения ввода и доступа к
+локальному управлению. Клавиши яркости управляют физическим экраном хоста.
+Общий буфер обмена и общие папки не включаются автоматически.
+
+Завершение или сбой просмотрщика либо композитора не выключает VM. Повторный
+запуск сессии подключается к работающим машинам. Ошибка подключения показывается
+коротким сообщением с возможностью повторить подключение или открыть аварийный
+терминал; она не приводит к автоматическому сбросу VM.
+
+Управляющие команды не передаются через гостевую клавиатуру. Горячие клавиши
+хоста должны срабатывать и при захваченном вводе просмотрщика. Отключение всех
+привязок labwc через ToggleKeybinds не подходит без проверки аварийного выхода
+и переключения VM.
+
+## Проверка перед упаковкой в ISO
+
+Используются отдельные временные VM и диски. Сначала проверяется вложенная
+тестовая сессия, затем самостоятельная сессия на TTY: первая не доказывает
+корректность захвата клавиш или работу физического экрана.
+
+Критерии приёмки:
+
+1. Два гостя переключаются клавишами без рамок, панели и интерфейса просмотрщика.
+2. Фоновая задача в скрытой VM продолжает работу; QEMU не перезапускается.
+3. Meta, Alt+Tab, раскладка и указатель работают в госте, а переключение VM,
+   яркость и аварийный выход остаются доступны хосту.
+   Проверяется также смена VM при удерживаемых модификаторах и кнопке мыши:
+   в покинутом госте не остаются зажатыми клавиши, а в новом не возникают
+   случайные действия из-за переданных отпусканий или состояния ввода.
+4. После закрытия просмотрщика или сессии VM остаются доступны по сети;
+   повторное подключение восстанавливает изображение.
+5. В обычной сессии хоста работает оконный просмотрщик и общее управление VM.
+6. Измеряются задержка переключения и обновление скрытых поверхностей. Замена
+   композитора не считается доказательством исправления ограничений VirGL/SPICE
+   или достижения 144 FPS. Если существующие просмотрщики не обеспечивают
+   требуемое поведение, выбор способа вывода пересматривается до сборки ISO.
+
+На этом этапе не создаются собственный композитор, графическая панель управления,
+установщик или механизм обновления дистрибутива. Сначала проверяется пригодность
+минимальной сессии для ежедневного использования.
+
+## Основания выбора
+
+- [labwc](https://labwc.github.io/) и его
+  [действия](https://labwc.github.io/labwc-actions.5.html): готовые механизмы окон,
+  полноэкранного режима, рабочих пространств и клавиатурного управления.
+- [Cage](https://github.com/cage-kiosk/cage): вариант для одного собственного
+  приложения HydraOS; самостоятельное управление несколькими просмотрщиками
+  потребует дополнительной реализации.
+- [Weston kiosk-shell](https://wayland.pages.freedesktop.org/weston/toc/kiosk-shell.html):
+  полноэкранные приложения и распределение по экранам; переключение VM придётся
+  дополнительно проектировать.
+- [Smithay](https://github.com/Smithay/smithay): основа собственного композитора
+  на Rust, с существенно большим объёмом ответственности за графику и ввод.
+
+## Уточнения реализации
+
+- Python 3.11+ и стандартная библиотека для переносимого CLI `hydra`.
+- labwc >= 0.20.0: обязательные host bindings используют overrideInhibition.
+- Профили TOML, состояние и приватные Unix-сокеты QMP/SPICE разделены.
+- Meta/Alt+Tab и default mouse bindings хоста не подключаются.
+- Полный проект ведётся автономно; локальные патчи зависимостей разрешены.
+- Сборка Gentoo идёт в отдельном builder; физические диски не являются целями тестов.
+- Для первой версии выбран Gentoo systemd stage3: logind, cgroups и независимые
+  службы VM; выбор init является реализационной деталью, не требованием пользователя.