| 1 | # ADR 0026: Markdown — поверхности превью и размещение (`workspace.toml`) |
| 2 | |
| 3 | **Статус:** Superseded |
| 4 | **Дата:** 2026-04-08 |
| 5 | **Обновлено:** 2026-04-11 — подраздел «Внутренние отсылки»; ортогонально [0023](0023-markdown-diagrams-language-tooling.md). Подробности — [§ История](#adr0026-history). |
| 6 | |
| 7 | > **Superseded — актуальный канон:** [ADR 0069](0069-markdown-preview-tool-surface-and-renderer-decoupling.md) (MFD tool surface, renderer-first, без `forward_split`). Ниже — **история** размещения через `workspace.toml` и внутренние отсылки; для новых решений опираться только на **0069**. |
| 8 | |
| 9 | ## Связанные ADR |
| 10 | |
| 11 | | ADR | Роль | |
| 12 | |-----|------| |
| 13 | | [0010](0010-ui-modes-toml-configuration.md) | `workspace.toml`, merge бандла `UiModes/` и overlay репозитория `.cascade/workspace.toml` | |
| 14 | | [0021](0021-pfd-mfd-cockpit-attention-model.md) | превью как вторичная поверхность относительно лобового редактирования | |
| 15 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | отдельное окно как второй `TopLevel` | |
| 16 | | [0022](0022-mfd-visual-design-surface-axaml-blazor.md) | перспектива вкладки/региона на MFD | |
| 17 | | [0023](0023-markdown-diagrams-language-tooling.md) | LSP, диаграммы, Kroki, export — **ортогонально** размещению виджета превью | |
| 18 | |
| 19 | ## Резюме |
| 20 | |
| 21 | - **Исторический** канон размещения Markdown preview (`workspace.toml`, `forward_split`). |
| 22 | - **Не использовать для новых решений** — см. callout и [0069](0069-markdown-preview-tool-surface-and-renderer-decoupling.md). |
| 23 | |
| 24 | |
| 25 | ## Замена прежних формулировок |
| 26 | |
| 27 | - **Этот ADR superseded** новым каноном в [0069](0069-markdown-preview-tool-surface-and-renderer-decoupling.md): preview больше рассматривается как отдельный tool surface с renderer/placement decoupling, а `forward_split` снят с канона. |
| 28 | - **Исторический канон по размещению превью Markdown** — этот ADR; актуальный канон для surface/renderer-decoupling — [0069](0069-markdown-preview-tool-surface-and-renderer-decoupling.md). |
| 29 | - Ранее единственное упоминание «Markdown preview» в контексте UX в [0023](0023-markdown-diagrams-language-tooling.md) § «Детали UX» **снято с канона** там и **заменено ссылкой сюда** ([0023](0023-markdown-diagrams-language-tooling.md) остаётся про языковой опыт и диаграммы). |
| 30 | - [0023](0023-markdown-diagrams-language-tooling.md) **не** superseded целиком — только пересечение по «где показывать превью». |
| 31 | |
| 32 | --- |
| 33 | |
| 34 | ## Контекст |
| 35 | |
| 36 | Нужна одна точка правды для **где** в UI монтируется отрендеренный Markdown: рядом с текстом во **forward** (лобовое), в отдельном **окне**, или в зоне **MFD** (вторичное внимание). Это решение про **хром и топологию виджета**, а не про LSP, include или Kroki. |
| 37 | |
| 38 | Конфигурация логично живёт в **`workspace.toml`** вместе с остальными глобальными метриками хрома ([0010](0010-ui-modes-toml-configuration.md)): один merge-слой с бандлом и overlay репозитория, без обратной записи динамического ресайза в шипнутые файлы. |
| 39 | |
| 40 | --- |
| 41 | |
| 42 | ## Решение |
| 43 | |
| 44 | 1. **Ключ TOML:** `markdown_preview_placement` в корне merged **`UiWorkspaceToml`** (модель и snake_case → PascalCase — как у остальных полей `workspace.toml`). |
| 45 | |
| 46 | 2. **Допустимые строковые значения** (регистр строки для пользователя не важен; в коде парсинг нормализует): |
| 47 | - **`forward_split`** — вторая колонка у активного документа редактора (`EditorContentGrid` в `DockDocumentView`), inline `MarkdownScrollViewer`. Неактивные вкладки держат ширину колонки превью **нулевой**, чтобы не копить «залипшую» раскладку на фоне. |
| 48 | - **`separate_window`** или синоним **`window`** — существующее окно `MarkdownPreviewWindow` (вторичный `TopLevel` в смысле [0017](0017-multi-window-workspace-and-agent-surfaces.md), без обязательной привязки к мультиоконной дорожной карте целиком). |
| 49 | - **`mfd`** — **целевое** размещение во вкладке/регионе зоны MFD ([0021](0021-pfd-mfd-cockpit-attention-model.md), перекрёстно с [0022](0022-mfd-visual-design-surface-axaml-blazor.md)). Пока отдельная вкладка под превью в MFD **не подключена**, поведение — **явный fallback** на отдельное окно (как зафиксировано в коде и комментариях), без молчаливого «как forward». |
| 50 | |
| 51 | 3. **Значение по умолчанию** до загрузки merged TOML и при сбросе тестов: **`forward_split`** (`MarkdownPreviewPlacementRuntime`). |
| 52 | |
| 53 | 4. **Связь с моделью внимания [0021](0021-pfd-mfd-cockpit-attention-model.md):** превью остаётся **вторичной** поверхностью относительно набора текста в лобовом редакторе; выбор `markdown_preview_placement` меняет только **геометрию монтирования**, не переопределяя семантику зон PFD/MFD/EICAS. |
| 54 | |
| 55 | 5. **Не путать** с будущим ключом **общей** «топологии презентации» нескольких `TopLevel` (обсуждение в [0010](0010-ui-modes-toml-configuration.md) / [0017](0017-multi-window-workspace-and-agent-surfaces.md)): `markdown_preview_placement` — **узкий** ключ только для превью Markdown. |
| 56 | |
| 57 | ### Глубина превью (намерение для v1) |
| 58 | |
| 59 | Превью в IDE — **вспомогательная** поверхность ([0021](0021-pfd-mfd-cockpit-attention-model.md)): целевая планка **«достаточно хорошо, чтобы доверять черновику и диаграммам»** (структура, кодовые блоки, ссылки, рендер диаграмм по правилам приватности/Kroki), а не **отдельный продукт-класса Typora/GitHub**. |
| 60 | |
| 61 | **Выше приоритетом**, чем «ещё круче визуально в панели превью», держим **контракт публикации**: собранный/развёрнутый документ для наружу — [0023](0023-markdown-diagrams-language-tooling.md) (export expanded, include, согласованность с внешним Markdown). |
| 62 | |
| 63 | **Не цель v1** (пока нет явного запроса и боли): пиксель-в-пиксель как GitHub, полноценный WYSIWYG вместо редактора, тяжёлый синхронный скролл с подсветкой блока «как в редакторах только превью». Узкий **forward_split** заведомо отнимает ширину у редактора — кто принципиально не хочет делить лобовое место, выбирает **`separate_window`** / **`window`** или (когда будет) **`mfd`**. |
| 64 | |
| 65 | ### Внутренние отсылки в длинных документах (peek / «Show Definition») |
| 66 | |
| 67 | **Проблема:** в ADR и длинных спеках часто встречаются отсылки **«см. п. 6 выше»** / **«п. 6»** без якорной ссылки — читателю или автору приходится **крутить** документ, чтобы вспомнить содержание пункта. |
| 68 | |
| 69 | **Намерение (не смешивать с языковым слоем [0023](0023-markdown-diagrams-language-tooling.md)):** в **виджете превью** (тот же хост, что задаётся `markdown_preview_placement` выше) — UX в духе **Peek Definition** / hover: наведение или жест на отсылку к **внутреннему** фрагменту текущего файла показывает **краткий оверлей** с целевым абзацем (или переход по клику), **без** обязательной прокрутки редактора. |
| 70 | |
| 71 | **Резолв цели:** |
| 72 | |
| 73 | - **Предпочтительно в авторинге:** обычные Markdown-ссылки — `[см. п. 6](#adrNNNN-p6)` к якорю `<a id="adrNNNN-p6"></a>` в том же ADR; канон имён — [snippets/adr-anchors-policy.md](snippets/adr-anchors-policy.md) (краткая отсылка: [README ADR](README.md#adr-anchors-policy)). |
| 74 | - **Эвристика (опционально):** распознавание текста вида «п. 6» / «§6» относительно **нумерованного списка** в секции «Решение» и подобных — только если явно окупает поддержку; при **неоднозначности** — **на стороне пользователя** (выбор из кандидатов или переход к якорю), без обязательной магии «лучший экран». |
| 75 | |
| 76 | **Приоритет:** ниже **базового** качества превью и **контракта публикации** ([0023](0023-markdown-diagrams-language-tooling.md), export); может войти в **последующую** итерацию после стабильного рендера и размещения по этому ADR. |
| 77 | |
| 78 | ## Связанные ADR |
| 79 | |
| 80 | | ADR | Роль | |
| 81 | |-----|------| |
| 82 | | [0017](0017-multi-window-workspace-and-agent-surfaces.md) | отдельное окно превью — уже вторичный `TopLevel` | |
| 83 | --- |
| 84 | |
| 85 | ## Реализация (ориентир по коду) |
| 86 | |
| 87 | - Модель: `UiWorkspaceToml.MarkdownPreviewPlacement`, merge: `UiWorkspaceTomlMerger`. |
| 88 | - Рантайм: `MarkdownPreviewPlacement`, `MarkdownPreviewPlacementParser`, `MarkdownPreviewPlacementRuntime`; подключение при загрузке каталога режимов — `UiModeCatalog` (рядом с `UiWorkspaceLayoutRuntimeMetrics`, `AttentionZonePanelRuntime`). |
| 89 | - UI: `DockDocumentView` — сетка редактора и inline-превью; `MainWindow` — ветвление команд превью по `MarkdownPreviewPlacementRuntime.Current`. |
| 90 | |
| 91 | --- |
| 92 | |
| 93 | ## Последствия |
| 94 | |
| 95 | - Документация для агента/MCP: при смене размещения снимок UI может показывать превью в разных регионах; контракт мульти-корня ([0017](0017-multi-window-workspace-and-agent-surfaces.md)) применим к отдельному окну превью. |
| 96 | - Расширение **`mfd`** без изменения ключа: отдельная поставка — вкладка/хост в MFD shell и снятие fallback. |
| 97 | - Реализация **внутренних отсылок** (подраздел выше): парсер/хост превью или слой поверх рендера; при необходимости — договорённости для авторов ADR (якоря vs «п. N») в [README индекса ADR](README.md), без нового ADR. |
| 98 | |
| 99 | --- |
| 100 | |
| 101 | ## Отклонённые альтернативы |
| 102 | |
| 103 | - **Держать размещение превью только в пользовательском `settings.toml`** — отклонено для пресета «как у проекта»: команда должна иметь возможность зафиксировать поведение в repo overlay рядом с остальным `workspace.toml`. |
| 104 | - **Сливать с [0023](0023-markdown-diagrams-language-tooling.md) одним ADR** — отклонено: смешивает языковой опыт и геометрию UI, усложняет навигацию и эволюцию по независимым осям. |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | ## История изменений |
| 109 | |
| 110 | <a id="adr0026-history"></a> |
| 111 | |
| 112 | | Дата | Изменение | |
| 113 | |------|-----------| |
| 114 | | 2026-04-08 | подраздел «Глубина превью»: целевая планка v1, non-goals, приоритет export из [0023](0023-markdown-diagrams-language-tooling.md). | |
| 115 | | 2026-04-11 | подраздел **«Внутренние отсылки»** (hover/peek по «см. п. N» и якорям); ортогонально [0023](0023-markdown-diagrams-language-tooling.md). | |
| 116 | |