| 1 | # ADR 0032: HUD над редактором — настраиваемое содержимое и грамматика (как у `presentation`) |
| 2 | |
| 3 | **Статус:** Proposed (намерение зафиксировано; реализация — по плану). |
| 4 | **Дата:** 2026-04-11 |
| 5 | |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | PFD / MFD — модель внимания кокпита Cascade IDE | |
| 11 | | [0085](0085-editor-hud-inline-layer-and-hud-banner.md) | термины **Editor HUD** vs **HUD banner** — этот ADR про конфиг **баннера** | |
| 12 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | строка `presentation`, секция `[presentation_grammar]`, EBNF в ADR | |
| 13 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | `settings.toml` | |
| 14 | | [0029](0029-configuration-toml-canonical-ui-facade.md) | канон на диске, UI как фасад | |
| 15 | | [0030](0030-command-ids-hotkeys-and-ui-registry-layers.md) | ортогонально командам | |
| 16 | |
| 17 | --- |
| 18 | ## Контекст |
| 19 | |
| 20 | По [0021](0021-pfd-mfd-cockpit-attention-model.md) **HUD** — слой **внутри лобового** (редактора), не четвёртый пространственный якорь; в него входят inline-диагностика, ghost text, полоса над текстом и т.п. Это уже было здесь буквально; [0085](0085-editor-hud-inline-layer-and-hud-banner.md) не меняет тот канон, а даёт имена **Editor HUD** (весь такой слой) и **HUD banner** (только file-level полоса), чтобы не отождествлять «HUD» с одной полоской. **Этот ADR** — про настраиваемость именно **баннера**: сейчас **текст полосы** над редактором задаётся кодом (сводка по диагностикам активного файла, фиксированные формулировки) — см. `MainWindowViewModel` (частичный класс с HUD). |
| 21 | |
| 22 | Параллельно для **топологии экранов** уже принят паттерн: строка в настройках (`presentation` / `zone_screen_layout`) + **настраиваемые токены** в TOML (`[presentation_grammar]`), парсер с тестами, спецификация в виде EBNF в [0017](0017-multi-window-workspace-and-agent-surfaces.md). |
| 23 | |
| 24 | Идея продукта: **вынести в пользовательский конфиг**, *что* и *в каком виде* показывает **HUD banner** (полосу над редактором), и по возможности использовать **тот же архитектурный приём**, что и для `presentation`: канон в `settings.toml`, опциональная секция грамматики, явная семантика источников данных. |
| 25 | |
| 26 | ## Решение (намерение) |
| 27 | |
| 28 | <a id="adr0032-p1"></a> |
| 29 | |
| 30 | 1. **Слой хранения:** как и для `presentation`, описание содержимого **HUD banner** — **прежде всего** в пользовательском **`settings.toml`** ([0028](0028-user-settings-toml-localappdata-and-secrets.md)); не дублировать логику «репозиторий vs личные настройки» иначе, чем в существующих ADR по конфигу. |
| 31 | |
| 32 | <a id="adr0032-p2"></a> |
| 33 | |
| 34 | 2. **Два уровня настройки (целевой минимум):** |
| 35 | - **Семантика:** какие **источники** могут участвовать в **строке HUD banner** (например сводка диагностик по активному документу, позже — другие сигналы), вкл/выкл, приоритет при конфликте площади или внимания — в духе Dark Cockpit из [0021](0021-pfd-mfd-cockpit-attention-model.md) §9. |
| 36 | - **Представление:** шаблон строки и/или мини-DSL для порядка фрагментов (плейсхолдеры вроде чисел ошибок/предупреждений, разделители); человекочитаемые строки по умолчанию — из i18n-слоя ([0033](0033-internationalization-resx-avalonia.md)), не из обязательной простыни в TOML. |
| 37 | |
| 38 | <a id="adr0032-p3"></a> |
| 39 | |
| 40 | 3. **Грамматика по аналогии с `presentation`:** опциональная секция в TOML (рабочее имя — например **`[hud_grammar]`** или согласованное с моделью `CascadeIdeSettings`) задаёт **литералы и разделители**, если строка конфигурации **HUD banner** становится разбираемой мини-языком (скобки, склейка блоков, запрет «магических» символов только в коде). Дефолты должны совпадать с текущим поведением там, где оно станет каноном. |
| 41 | |
| 42 | <a id="adr0032-p4"></a> |
| 43 | |
| 44 | 4. **EBNF и реализация:** грамматика **документируется** в ADR (как для `presentation` в [0017](0017-multi-window-workspace-and-agent-surfaces.md)) для ревью и справки. **Реализация** — прагматично: небольшой ручной парсер + тесты, **пока** язык узкий; подключение **генераторов из EBNF** или тяжёлых библиотек парсинга — только если DSL **расширится** настолько, что ручная поддержка становится дороже зависимости (аналогично обоснованию для `presentation`, где уже используется явный парсер, а не ANTLR). |
| 45 | |
| 46 | <a id="adr0032-p5"></a> |
| 47 | |
| 48 | 5. **Границы:** этот ADR **не** меняет семантику зон внимания ([0021](0021-pfd-mfd-cockpit-attention-model.md), [0025](0025-sdk-attention-zones-and-capabilities.md)) и **не** обещает конкретный набор плейсхолдеров до проектирования; **не** смешивать конфиг **HUD banner** с размещением окон ([0017](0017-multi-window-workspace-and-agent-surfaces.md)). |
| 49 | |
| 50 | ## Последствия |
| 51 | |
| 52 | - Появится явный контракт в коде: модель настроек (`CascadeIdeSettings` или вложенный тип), разбор шаблона/DSL, тесты парсера и регрессии текста баннера. |
| 53 | - Документация пользователя (когда будет слой User Guide) сможет ссылаться на один канон в TOML вместо «как захардкожено в сборке». |
| 54 | |
| 55 | ## Отклонённые / отложенные альтернативы |
| 56 | |
| 57 | - **Только UI без канона на диске** — противоречит [0029](0029-configuration-toml-canonical-ui-facade.md); точечный UI возможен как фасад, но источник истины — TOML. |
| 58 | - **Сразу генератор парсера из EBNF** — избыточно для первой итерации; пересмотреть при росте DSL ([п. 4](#adr0032-p4)). |
| 59 | |
| 60 | ## Открытые вопросы |
| 61 | |
| 62 | - Точные имена ключей TOML и полей в `CascadeIdeSettings` (согласовать с snake_case и merge-слоем из [0028](0028-user-settings-toml-localappdata-and-secrets.md)). |
| 63 | - Нужна ли **отдельная** строка-шаблон или достаточно структурированных булевых флагов + один шаблон форматирования чисел. |
| 64 | - Формулировки UI по умолчанию для HUD и прочих поверхностей — из слоя локализации ([0033](0033-internationalization-resx-avalonia.md)), а не обязательные длинные переводы в TOML. |
| 65 | |