# 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 является реализационной деталью, не требованием пользователя.