fabrilis/docs/UI.md
loki5512344 878d144b77 Initial commit: Fabrilis docs, rules and deterministic core
Docs (architecture, decisions, coupling, determinism, UI, references), code rules enforced by tools/limits, deterministic core with units, time, math, sched, snapshot, vec and rng, plus smoke tests. ref/ stays out of git.
2026-11-16 23:06:29 +01:00

88 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# UI
UI Fabrilis — это редактор и отладочный оверлей внутри приложения, а не отдельный
UI-фреймворк и не библиотека для чужих программ. Окно обычное прямоугольное,
управление окном и вводом — на `winit` (D24), рисование — на нашем `wgpu`-рендере,
готовые UI-библиотеки не берём (D20).
## Модель
- **Immediate-mode на старте.** UI каждый кадр строит список команд рисования
(прямоугольник, скруглённый прямоугольник, линия, текст, картинка, клип), рендер
батчит их. Состояние виджетов живёт в приложении, а не в дереве UI.
- **Retained-дерево только по доказанной нужде.** Если профилирование покажет, что
пересборка команд дорога, вводим стабильные `NodeId`, dirty-флаги и кеш ресурсов.
Reconciliation и анимационный граф заранее не пишем.
- **Event-driven redraw.** Нет изменений — нет кадра. Каждый кадр имеет причину
(`Input`, `Animation`, `Resize`, `SimulationTick`, `Debug`), счётчик причин виден
в оверлее; в простое — 0 кадров/с.
- **Кеш ресурсов.** Пайплайны кешируются по `shader + layout + format + blend`;
текст — через общий glyph atlas, а не текстуру на надпись. Offscreen-проходы
только там, где эффект этого требует.
- **Capability-модель.** Вместо `bool` — `Available | Unavailable { reason } |
Conditional { reason }`: «нет прозрачности», «fractional scale не поддержан»,
«эффект недоступен на этом backend'е». Не выполнять молча.
## Что есть в M4 и M10
| Этап | UI |
|---|---|
| M4 | оверлей отладки: FPS/RTF, число тел, причины кадров, время подсистем; прямоугольники, текст, линии, клип |
| M10 | панели и сплиттеры, дерево конструкции, таблица свойств, графики, 3D-вид, диалоги, текстовые поля |
Виджеты вводятся по одному и только под конкретную задачу редактора. Зоопарк
«на будущее» запрещён (KISS).
## Текст
- Сейчас: `fontdue` только растеризует глифы, раскладку строк и переносы делаем сами.
Для латиницы и кириллицы этого достаточно.
- Текстовые поля требуют shaping и IME. Решение отложено до M10: кандидаты —
`cosmic-text` или `Parley` (+ `glyphon` для wgpu). Берём только когда появляется
настоящее поле ввода, с записью в DECISIONS.md.
- Курсор, выделение, копирование и IME не эмулируем частично: либо полноценно, либо
поле ввода не выпускаем.
## Что взято из ShapeUI blueprint
Локальная копия: `ref/shapeui-blueprint_v0.2_revised_ru.md` (в git не входит).
Из него берём идеи, не архитектуру:
- event-driven redraw и счётчик причины кадра;
- render command list и батчинг вместо draw call на виджет;
- общий glyph atlas;
- раздельные dirty-флаги (стиль, layout, текст, геометрия);
- capability-модель вместо обещаний `bool`;
- оверлей диагностики: PSS/RSS, draw calls, offscreen passes, кеши, причина кадра;
- дисциплину «сначала панели/текст/ввод, потом виджеты».
## Что из ShapeUI не берём
- Окна произвольной формы, click-through, `wl_region`, `set_input_region`: у нас
обычное окно, этим занимается `winit`.
- Свой Wayland-backend и raw `wl_surface`: дублирует `winit`.
- CPU-рендерер, Vello, несколько backend'ов, morphing, shader marketplace.
- Собственный scene graph с реконсиляцией до доказанной необходимости.
- Доступность (AccessKit) с первого дня; вернёмся к ней перед публичным релизом.
## Диагностика
Оверлей показывает то, что можно проверить:
```
PSS / RSS 38.4 / 51.1 MiB (estimated)
draw calls 6
offscreen 1
pipelines 5
glyph atlas 2.1 MiB
frames last 10s 0
last frame Idle
```
Числа не выдаются за «всю VRAM процесса»; приблизительные помечаются `estimated`.
## Открыто
- Shaping и IME для текстовых полей: `cosmic-text` или `Parley`, решаем на M10.
- Нужен ли retained-слой: решаем по профилировке M10, не заранее.
- Графики: своя простая отрисовка линий и областей; библиотеку не берём.