HUD)¶

Статус: Proposed
Дата: 2026-04-08

Связанные ADR¶

ADR	Роль
0021	семантика зон и каналов внимания
0024	SDK, capability‑модель, `CascadeIDE.Contracts`
0010	overlay презентации без подмены семантики

Контекст¶

0024 вводит SDK как способ держать единую ментальную модель продукта (модули, capabilities, introspection). Отдельно 0021 задаёт модель внимания кокпита: три пространственных якоря (Forward, Pfd, Mfd), канал оповещений Eicas, слой Hud на лобовом.

Сегодня зоны реализованы в приложении (AttentionZone, AttentionZoneIds, маппинг панелей — например AttentionZonePanelRuntime), а CascadeIDE.Contracts не содержит явной оси «зона внимания» для UiSurfaceCapabilityDescriptor / команд. Из‑за этого SDK и кокпитная геометрия живут рядом, без формального моста: агент, диагностика и overlay не могут опереться на один канонический словарь зон на уровне контрактов.

Нужно зафиксировать отдельное решение: как связать capability‑слой с моделью внимания, не раздувая SDK и не дублируя разметку Axaml.

Решение¶

Канон зон — тот же, что в 0021 и в коде: строковые id forward, pfd, mfd, eicas, hud (см. AttentionZoneIds / AttentionZone.ToCanonicalId()). Семантика «EICAS — канал, не четвёртый якорь-колонка» не меняется.
SDK должен уметь выражать привязку capabilities к зоне внимания как метаданные, а не как дублирование визуального дерева:
минимум: опциональное поле на UiSurfaceCapabilityDescriptor (и при необходимости на CommandCapabilityDescriptor, если команда считается привязанной к зоне по смыслу — напр. фокус в редакторе);
значение: канонический id зоны (строка, совместимая с TOML overlay и capability‑map), либо ссылка на общий enum/константы в CascadeIDE.Contracts после выноса.
для поверхностей, совпадающих с панелью shell: опциональное HostAttentionPanelId (AttentionPanelCanonicalIds) вместе с PrimaryAttentionZoneId — мост к AttentionZonePanelRuntime; см. attention-zone-panel-playbook-v1 и проверку CapabilityAttentionConsistency при сборке карты.
Презентация по-прежнему через overlay (0010, 0024): видимость, размер, вкладка MFD shell — не переносятся целиком в SDK. Зона в контракте отвечает на вопрос «где в модели внимания живёт эта поверхность», а не «в каком пикселе».

Нативные диалоги (Open/Save) и метаданные зоны¶

Зона в SDK не задаёт, что выбор файла или решения обязан рисоваться внутри MFD/Forward как встроенная панель. Это отдельное решение пресета и UX (0010); при необходимости его явно проектируем (онбординг, режимы), а не выводим из одного поля «зона».
Системные диалоги открытия/сохранения на десктопе обычно реализуются как отдельное top-level окно (модально к приложению); типичные API не предназначены для встраивания того же UI «в ячейку» сетки кокпита как дочернего виджета. Имеется в виду: нативный выбор — это оверлей поверх сцены, хотя команда могла быть вызвана из зоны (кнопка в MFD, палитра и т.д.).
Политика продукта (по умолчанию): опираться на нативный диалог ОС для выбора пути/файла, чтобы не отнимать у пользователя привычный проводник и интеграции облака/ОС; свой встроенный браузер файлов в области shell — только если это осознанное решение сценария (inline-опыт, единая сцена для агента и т.п.), а не обязательное следствие модели зон.
Избыточность: навязывать всем командам заполненную зону «для галочки» не нужно; команды с глобальным смыслом (палитра, настройки, открытие файла через системный диалог) могут оставаться без первичной зоны в метаданных или с зоной только там, где это реально помогает карте capabilities (см. открытые вопросы ниже).
Реализация — поэтапно:
Фаза A (документ): этот ADR + ссылка из 0024.
Фаза B (контракты): сделано: AttentionZoneCanonicalIds + опциональное PrimaryAttentionZoneId на CommandCapabilityDescriptor и UiSurfaceCapabilityDescriptor; строковые id в приложении (AttentionZoneIds) алиасят константы из Contracts.
Фаза C (реестр): заполнять поля при регистрации модулей по смыслу; CapabilityMap и JSON-дампы содержат зону и HostAttentionPanelId (сериализация record). При обоих заданных — согласованность с AttentionZonePanelRuntime (предупреждение в Debug при BuildMap()). Playbook: attention-zone-panel-playbook-v1.
Фаза D (опционально): снять оставшееся дублирование — enum/расширения только в приложении, строки — из Contracts везде, где уместно.
Стабильность: новые поля в Experimental namespace контрактов; изменение набора зон или id — только с обновлением 0021 и этого ADR.

Последствия¶

Capability‑map и агентские сценарии смогут отвечать: «эта UI‑поверхность задекларирована как MFD», без чтения Axaml.
Появляется явная связь между продуктовой метафорой кокпита и машиночитаемым SDK — то, что ожидалось от «ментальной модели в SDK», но вынесено в отдельное решение, чтобы не смешивать с общим scope 0024.
Риск: лишняя формальность, если регистрировать зону «для галочки». Митигация: поле опционально; дефолт «не задано», пока фича не осознанно относится к зоне.

Отклонённые альтернативы¶

Только теги в Tags без канона — слишком слабо для инструментов и валидации overlay.
Полная схема layout в SDK — избыточно; разметка остаётся в UI, в SDK — только семантическая ось внимания.
Всё держать только в 0024 — размывает документ и смешивает два уровня решений (общий SDK vs кокпитная ось).

Открытые вопросы¶

Нужна ли явная привязка Service capability к зоне (обычно нет — сервис без UI) vs только UiSurface (да).
Нужен ли отдельный тип «зона не применима» для команд, которые глобальны (палитра, настройки).