shturman/docs/domains/c-shell-ux.md

Домен C — Shell / UX / лаунчер

Лицо продукта и UI-хост: Wayland-композитор, который рисует home/тайлы и темы, и в слоты которого встраивается UI всех апов/плагинов. v0-артефакт и главный UX-дифференциатор («красиво и не лагает» против китайских блоков).

Статус: v2 (на ревью). v2 — после ретро-ревью (6 находок). Связано с: architecture.md (#6 хостинг UI) · ipc.md (Shell, Location) · plugin-sdk.md (UI-вклад) · tech-stack.md (Slint) · security-privacy.md (consent UI) · principles.md (#6,#11) · домены D, E, K (GPS/Location)

---

1. Назначение и границы

• Что делает: хост UI + лаунчер + экраны + тема + driver-distraction; сам является Wayland-композитором.
• First-party, но с привилегированной ролью композитора (поднимается рано, Stage 1).
• Границы: не реализует логику апов (только хостит их UI); не трогает CAN/safety.

2. Композитор ⚠️ (корректировка cage)

• Shell = кастомный минимальный multi-client Wayland-композитор на smithay (Rust, ложится на Rust-first). GPU — Panfrost/Mesa.
• ⚠️ cage (значился в tech-stack/dev-env) НЕ подходит: это single-app kiosk-композитор, он не умеет хостить поверхности нескольких клиентских процессов — а наша слот-модель (решение #6) именно про это. cage остаётся лишь как инструмент раннего bring-up одного приложения. → правлю tech-stack и dev-environment. (Альтернатива smithay — wlroots, но это C-библиотека и нужны биндинги; smithay роднее.)
• Объём/риск и v0: полноценный композитор — серьёзная работа, и v0 её не требует (нет сторонних плагинов, почти нет отдельных surface-апов). v0-shell стартует как Slint-приложение (home/тайлы/настройки, без внешних поверхностей); полный smithay-композитор включаем, когда придёт первый surface-ап (нав/медиа/камера) — это де-рискует v0.

3. Функции

функция	MVP/later	зависит от	фаза
Home с крупными тайлами	MVP	—	v0
Тема день/ночь (авто)	MVP	—	v0
Быстрый boot / первый кадр (Stage 1)	MVP	architecture §6	v0
Slint-shell: home/тайлы/настройки (без внешних поверхностей)	MVP	—	v0
Декларативный рендер тайлов/карточек	MVP	—	v0
Полный smithay-композитор (мульти-клиент) + слот-поверхности	later	—	с первым surface-апом (нав/медиа)
Статус-бар: время, сеть (с initial «unknown»)	MVP	Connectivity, время (a-base §7)	v0
Статус-бар: быстрый статус машины	later	E	v2
Анимации/переходы (полировка)	MVP	—	v0
Экран настроек (растёт: тема/единицы v0 → голос/LLM v1 → плагины v3)	MVP	Settings	v0+
Интеграция ассистента (PTT + лог диалога)	MVP	D	v1
Driver-distraction режим	MVP	K (GPS speed) v1 / E (OBD speed) v2	v1/v2
Ввод с мультируля (кнопки руля)	later	K/E	v1/v2
UI управления разрешениями (review/revoke)	later	security-privacy	v3
Мультидисплей · профили водителей · виджеты	later	—	later

Статус-бар, начальный/деградированный контракт: индикатор сети на первом кадре — «unknown» (Connectivity не в Stage 1) → реактивно GetStatus()/ConnectivityChanged; Online бинарный, «сервис не поднят» ≠ «offline» (не рисуем «offline» до первого ответа). Часы: до синка времени (a-base §7) — пометка неопределённости/скрыть, не показывать возможно-неверное cold-boot-значение.

4. Слот-модель (решение #6)

Слоты: home-грид, полноэкранная зона, оверлей (ассистент/уведомления), статус-бар. Ап вкладывает в слот декларативный элемент или Wayland-поверхность.

Механизм поверхности (не «handle по D-Bus»): ап подключается клиентом к Wayland-сокету Shell (его пробрасывает bubblewrap при ui_*, security-privacy §4) и создаёт там surface; привязка surface→слот — через приватный Wayland slot-протокол (ru.shturman.shell_slot), не по D-Bus. RegisterScreen по D-Bus возвращает slot-token, который клиент предъявляет в slot-протоколе; композитор сверяет peer-credentials сокета. Гейтится capability ui_screens (тайлы — ui_tiles; plugin-sdk §4.1).

5. Декларативный UI-DSL (резолв отложенного вопроса)

• Констрейнт-набор, не произвольная вёрстка: tile (icon/title/value/state/action), card, простой list/form (для настроек) — всё data-bound.
• Рендерит сам shell в Slint → единый стиль и безопасность (чужой код не исполняем).
• Что не выражается этим набором → Wayland-поверхность (ап рисует сам).
• Покрывает частые ~80% (тайлы/карточки/настройки); богатое (карта/видео) — поверхностью.

6. Тема и отклик

• День/ночь — авто (v0: по времени (RTC/NTP/fake-hwclock, a-base §7); GPS-восход — v1 (после поднятия домена K); датчик освещённости и сигнал машины — later), токены темы (design-system.md — визуальный язык).
• Крупные тач-таргеты, мгновенный отклик (принцип #11): тяжёлое — фоном, UI-поток не блокируем.

7. Driver-distraction (принцип #6)

• Выше порога скорости → упрощённый UI, приоритет голосу, блокировка сложных взаимодействий.
• Источник скорости: GPS (домен K, ru.shturman.Location) уже в v1 (раньше OBD), уточняется OBD-скоростью (E) в v2. C потребляет занулённую/quality-флагнутую Speed от K §2 (не сырой Doppler-шум на стоянке) — это source-level фикс, ортогональный гистерезису ниже.
• Fail-safe при неизвестной/устаревшей скорости (тоннель/нет фикса GPS, stale OBD — #3): гейт по умолчанию в консервативное состояние (к безопасности), таймаут staleness + видимая пометка «скорость неизвестна».
• Гистерезис/дебаунс: раздельные пороги on/off, чтобы джиттер не мигал режимами.
• Арбитраж (v2): правило GPS vs OBD (что авторитетно, поведение при расхождении/устаревании).
• Конкретные числа порога и список блокируемого — в открытых вопросах.

8. Интеграция ассистента (D)

• Лаконично, как Grok/Tesla: всегда доступная PTT-аффорданс + оверлей диалога в отдельном слоте; не отдельное «приложение», а ткань интерфейса.

9. Ввод

• Тач + мультируль: K нормализует кнопки (ADC-лесенка / проксированные CAN из E) в uinput → композитор Shell маршрутизирует их фокусом (штатный Wayland-input), не «Shell сам потребляет». Навигация по UI без касания; часть руль-действий сама гейтится distraction-режимом (K §3).

10. Зависимости

• Графика: Wayland (smithay) + Panfrost/Mesa; Slint (tech-stack).
• Хостит: UI апов/плагинов (App-Host их запускает; Shell композитит).
• Данные: K (ru.shturman.Location — GPS-скорость для distraction v1, день/ночь-восход), E (OBD-скорость уточнение v2 + быстрый статус машины), D (ассистент-UI), Settings, security-privacy (consent/permission UI), plugin-sdk (точки UI-вклада).

11. Открытые вопросы

• 🟡 Точная грамматика декларативного DSL (поля tile/card/list/form) — детализировать.
• ◻️ Пороги и политика driver-distraction (что именно блокируется и когда). → этот домен + principles #6.
• ◻️ UI управления разрешениями (review/revoke) — из security-privacy. → этот домен + Settings.
• ◻️ Источник день/ночь (v0 время; GPS-восход v1; датчик освещённости / сигнал машины — later). → реализация + домен K.
• ◻️ Мультидисплей, профили — later.
• ✅ Контракт Location/GPS — в k-sensors §2 (QoS, FixQuality, zero-clamp скорости у нуля; C потребляет занулённую Speed). Арбитраж GPS-vs-OBD (v2) — открыт.
• ◻️ Какие руль-действия гейтятся в distraction — парный с K §10.
• ◻️ Z-order overlay-слота (входящий-вызов G §6 vs реверс-вид J §6 vs ассистент/уведомления) — правило «вид манёвра > уведомление». → §4 + G/J.
• 🟡 Slot-протокол поверхностей (ru.shturman.shell_slot: surface→слот, slot-token, peer-creds) — спроектировать (§4).

---

Журнал решений (домен C)

Решение	Выбор	Дата
Композитор	кастомный multi-client на smithay (Rust); cage НЕ годится (single-app)	2026-06-16
Хостинг UI	слот-модель: декларативный элемент (рендерит shell) или Wayland-поверхность	2026-06-16
Декларативный DSL	констрейнт data-bound набор (tile/card/list/form); сложное → поверхность	2026-06-16
Тема	день/ночь авто; токены	2026-06-16
Скорость для distraction	GPS (домен K/Location) в v1, OBD (E) уточнение в v2; fail-safe при потере	2026-06-16
Поверхности	через Wayland slot-протокол ru.shturman.shell_slot + slot-token, не «handle по D-Bus»	2026-06-16