Files
phelex 0d171915d7 Add Site Studio themes and Theme Manager
Support categorized fragments, theme presets, block widths, and server-backed theme editing with onboarding and preview.

Include Site Studio, design sources, specification and verification reports; remove the legacy studio-site example.
2026-11-13 14:04:49 +03:00

144 lines
22 KiB
Markdown
Raw Permalink 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.
# Runtime 002 — файловая тема и ширина блоков
Реализованы этапы 1–3. Версия схемы сайта, страниц и темы — 1. Интерфейс Theme Manager, его endpoints и новый `examples/site-studio` относятся к этапам 4–5 и пока отсутствуют.
## Загрузка и источник истины
`site.yaml` содержит `theme: {file: theme.yaml}`; путь относительный, внутри корня сайта. Файл темы обязателен при явной ссылке. Неверные YAML/тип/путь, symlink наружу и inline-настройки дают диагностику с путём; ошибка блокирует build/preview. Если настройка темы вообще отсутствует, используется minimal@1 в памяти, файл не создаётся.
```yaml
schema: 1
preset: minimal
preset_version: 1
overrides:
colors:
primary: '#4255b9'
ui:
container:
mode: boxed
max_width: 1080
gutter: {desktop: 36, tablet: 24, mobile: 16}
```
`core/theme.py` предоставляет dataclass `ThemeDocument`, `EffectiveTheme`, `ContainerSettings`, `Gutters`, функции `preset_catalog`, `font_catalog`, `resolve_theme`, `load_theme`, `theme_css`. Ядро не требует Pydantic. Registry содержит вычисленную `theme`; `Site` содержит только ссылку `theme_file`.
Пресеты minimal/dark/editorial/bold/natural/custom и каталог шрифтов скопированы из `design/assets/theme-studio.js` в `builtin/themes/v1/*.json`. Runtime не читает design и не хранит отдельную палитру в БД/JS. Каталог отдаёт независимые копии; определения опубликованной версии не изменяются. Будущие изменения пресета требуют отдельной версии и поддержки этой версии в resolver.
Переопределения объединяются глубоко, поэтому изменение mobile gutter сохраняет desktop/tablet. `custom_colors` и явно заданный `gradients.definitions` заменяют соответствующую карту целиком: удалённые определения не возвращаются из defaults. Custom требует полный набор colors/type/ui, включая вложенный container/gutter. Дополнительные цвета и градиенты необязательны.
## Валидация
| Поле | Контракт |
|---|---|
| colors | background/surface/text/muted/primary/secondary/accent/border, HEX #RRGGBB |
| type | pair из каталога или custom, heading/body только разрешённые системные стеки |
| type.scale / line | числа 0.85–1.3 / 1.3–1.9 |
| type.headingWeight | целое 100–900 |
| ui.radius / spacing | числа 0–24 px / 0.8–1.4 |
| ui.shadow / button | none/soft/medium и solid/outline |
| ui.container | объект mode/max_width/gutter; старое число отклоняется |
| max_width / gutters | целое 720–1920 / целые 0–96 px |
| custom_colors | до 24 HEX; имена `[a-z][a-z0-9_]{1,31}`, без конфликтов с зарезервированными токенами |
| gradients | enabled: boolean, до 12 именованных linear definitions |
| definition | angle 0–360, 2–5 stops `{at: 0..100, color: HEX}`, позиции строго возрастают |
Неизвестные ключи, null вместо объекта, boolean вместо числа, строки с CSS/URL/Jinja и нечисловые/бесконечные значения отклоняются. Ошибки используют коды `E_THEME_*`. Проверяются контрасты text/background, text/surface, muted/surface; `W_THEME_CONTRAST` не блокирует публикацию. Включённые градиенты добавляют предупреждение о проверке контраста по всей поверхности.
## CSS и релиз
Порядок общего бандла: base.css → стили использованных фрагментов → вычисленные переменные → containers.css. Встроенные компоненты используют семантические переменные; дополнительных CSS из пользовательских данных нет.
| Токены | CSS |
|---|---|
| colors.name | `--color-name`; background также `--color-bg` |
| custom_colors.hero_ink | `--color-hero-ink`, адресное использование шаблоном |
| type | `--font-heading`, `--font-body`, `--type-scale`, `--type-line`, `--heading-weight` |
| ui | `--radius`, `--spacing`, `--shadow`, `--button-background`, `--button-text` |
| container/gutter | `--container`, `--container-max`, `--gutter-desktop/tablet/mobile`, responsive `--active-gutter` |
| gradients.definitions.name | `--gradient-name`; для hero/button/cta также `--hero-gradient`, `--button-gradient`, `--cta-gradient` |
Градиенты применяются адресно: тёмный Hero, основная solid-кнопка и CTA используют соответствующие роли. При отключении возвращаются однотонные значения, outline-кнопка остаётся прозрачной. Публичные CSS находятся в релизе/iframe, на skin админки не влияют.
Manifest содержит прежние source_hash/routes/fragments/page_sources и новые `render_hash`, `fingerprint`, `theme: {document, effective_tokens}`. ID строится из времени и общего fingerprint файлов сайта, кода ядра/сборки/парсинга, builtin-ресурсов, пресетов и загруженных фрагментов. При одинаковом ID существующий релиз переиспользуется только при побайтово одинаковом результате; несовпадение даёт `E_RELEASE_COLLISION` и сохраняет историю. Ошибка не переключает current. Rollback переключает готовый релиз и не меняет theme.yaml/контент workspace.
## Layout блока и конструктор
```yaml
- id: hero_home
fragment: hero
layout:
section_width: full
content_width: boxed
props:
title: Пример
```
Оба поля допускают inherit/boxed/fluid/full. Отсутствующий layout у hero/cta_banner/site_header/site_footer означает full/inherit; у остальных — inherit/inherit. Явный пустой объект или явно заданный inherit наследует глобальную ширину. Неизвестные ключи и режимы дают `E_BLOCK_LAYOUT`; молчаливого исправления нет.
Boxed ограничивает секцию до `min(available - 2*gutter, max_width)`, fluid убирает max_width, full занимает всю доступную ширину без gutter. Внутренний boxed-контейнер имеет max_width и padding, fluid — только padding, full — без ограничения и padding. Внешняя секция ограничивает внутреннюю. Gutters переключаются на 700 и 1024 px; для слишком узкого вложенного контейнера padding ограничен его доступной шириной.
Renderer ставит `data-engine-block`, `data-section-width`, `data-content-width` на существующие корни и `data-engine-container` на собственные `.f-container`/`.container`. Область вложенного блока исключается из обработки родителем. Для разделения фона и содержимого собственный шаблон должен иметь внешний корень и внутренний контейнер. Richtext/image/columns builtin получили собственные внутренние контейнеры; общий wrapper вокруг всех фрагментов не добавляется, sticky-header остаётся корнем. Preview markers добавляются отдельно; публикация их не содержит.
Один парсер применяется к Page, Display, Entry regions, fixed и slots. Снимки передают layout без потери данных. Transform меняет сырой YAML; props edit, duplicate, move, toggle, Save и reopen сохраняют layout. На API-границе `BlockLayoutDTO` объявляет enum в OpenAPI, `BlockValues` ограничивает поля, явный null для anchor/note сохраняет значение очистки. `schema.container` отдаёт глобальные настройки.
Контролы инспектора перенесены из `design/assets/builder.js:blockWidthControls`: те же названия, варианты, классы и пояснение. Обновление использует существующий HTML → внутренний JSON API → DocumentService; debounce и preview остаются асинхронными. Выбор секции локальный; изменение до Save не создаёт черновик на диске. Выделение и scroll preview сохраняются.
## Проверка и запуск
```bash
PYTHONPATH=src python -m unittest discover -s tests -p 'test_theme.py' -v
PYTHONPATH=src python -m unittest discover -s tests -p 'test_block_layout.py' -v
PYTHONPATH=src python scripts/qa_theme_002.py
PYTHONPATH=src python scripts/verify_package_001.py --site /path/to/isolated-site
```
Нужна пересборка образа/установка нового пакета. Рабочий SITE_ROOT не переключается автоматически; примеры обновлены только в исходниках. Root examples не коммитятся. Проверки и артефакты — в [отчёте](verification-stages-2-3.md).
## Этап 4: публичный builtin и отдельный Site Studio
Источник разметки/CSS — design/examples/site-studio/fragments и assets/site.css. Общие примитивы перенесены в builtin/base.css, правила компонентов — в их style.css. Служебные f-классы сохранены для существующих локальных шаблонов. Штатный сборщик добавляет тему и containers.css после этих правил. Готовый пакет не читает design/.
Добавлены content/steps (прежний title/items из ai-studio, локальный дубликат удалён) и data/entry_card. `entry_header` дополнен summary/image/image_alt, `form` — title/description. Метки Hero, шапки, записи, заголовок richtext и описание collection_list задаются опциональными props; тексты нового примера не захардкожены в общие шаблоны. Списки произвольной длины, slots, columns/page_header и card_grid.variant:steps сохранены.
`ref` с `to: '*'` использует collection/slug. Парсер/валидатор проверяют форму; Resolver различает E_REF_FORMAT, E_REF_COLLECTION, E_REF_MISSING, E_REF_UNPUBLISHED. Опубликованная карточка с недоступной целью блокирует build; preview показывает диагностику. Универсальные ссылки в данных коллекций проверяются и без использования в display, включая вложенные group/list/refs. Обычные ref/refs сохраняют slug и прежнюю семантику. Document schema предоставляет дополнительный choices.published_entries; generic datalist включает только эти записи, fixed datalist использует прежний choices.entries. Save/ETag/буфер не изменены.
Collection теперь поддерживает необязательный `requires: [feature.<имя>]` (schema остаётся 1). Неизвестное требование — E_REQUIRES_UNKNOWN. При выключенной feature записи сохраняются в workspace, не публикуются, не попадают в query или generic choices и не требуют release-полноты. Маршрут такой записи недоступен для generic ref. Без requires поведение прежнее. В новом примере courses/posts связаны с features courses/blog.
`examples/site-studio/` содержит адаптированные данные/ассеты/пять layouts с seo/assets hooks; штатный build создаёт 13 страниц и два редиректа. Сохранены 8 записей, 4 из которых draft. Намеренно отсутствующая обложка booking диагностируется в preview, не мешает live. Форма выполняет настоящий POST и показывает HTTP 501 без очистки ввода или перехода на thank-you. Нового FormService/доставки нет.
Отдельный запуск — examples/site-studio/README.md; QA — scripts/qa_site_studio_002.py; результаты — [verification-stage-4.md](verification-stage-4.md). Рабочие SITE_ROOT/data не изменяются.
## Этап 5: Theme Manager, API и мастер первого входа
Экран `/admin/theme` («Дизайн сайта») и `/admin/setup/theme` используют исходные HTML-композицию, CSS и контролы `design/theme-studio-antirion.html` / `design/assets/theme-studio.{css,js}`. Сохраняется принятый shell админки. Стили исходного экрана и его импортированные button/chip-примитивы ограничены `.theme-content`; публичные CSS остаются в iframe. Палитра темы сайта не меняет skin админки. Нативных browser dialogs и palette-localStorage нет.
JSON API (внутренние credentials, существующая request-scoped авторизация UI):
| Метод | `/admin/api/v1` | Результат |
|---|---|---|
| GET | `/theme` | ThemeSnapshot |
| GET | `/theme/presets` | 6 preset definitions, их документы/effective tokens, font catalog |
| PATCH | `/theme` | Save: `{document, if_match, revision}` → ThemeSnapshot |
| POST | `/theme/validate` | `{document, revision}` → ThemeSnapshot или 422 с diagnostics в error.issues |
| POST | `/theme/preview` | `{document, revision, target: sample\|page, page_id?, device: desktop\|phone, viewport_width?: 320..3840}` → immutable Preview |
| GET | `/theme/onboarding` | `{status, needs_setup, can_manage}` |
| POST | `/theme/onboarding/skip` | skipped |
| POST | `/theme/onboarding/restart` | in_progress |
HTML-адаптер принимает обычные form POST с `csrf` и `payload` (JSON DTO): `/admin/theme/save|validate|preview`; workflow — `/admin/setup/theme/skip|restart`. Он возвращает JSON-проекцию результата внутреннего AdminApi, не обращаясь к сервису/файлам напрямую. Внешние credentials браузеру не выдаются. Вход в экран выполняется обычной навигацией; htmx-переход получает HX-Redirect для корректной загрузки исходных ресурсов.
ThemeSnapshot: document, etag, effective_tokens, diagnostics, workspace_revision, live_build_id, revision; также path, yaml, css и contrast для UI. workspace_revision — хеш конфигурации сайта и ETag темы; это версия темы в workspace, не счётчик правок всех страниц. `revision` относится к состоянию текущей вкладки. Контракт экспортирован в `specs/001-antirion-admin/openapi.json` штатной командой export-openapi.
Клиент получает пресеты/шрифты/effective tokens с backend. Он редактирует доступные поля, отправляет полный документ (полный overrides допустим и для обычных пресетов). Второго JS resolver/валидатора/CSS-генератора темы нет. После паузы ввода идут серверная проверка и preview; это не Save. Переключение шага сохраняет iframe и не записывает контент. Desktop/Mobile и выбор реальной страницы создают новый snapshot. Устаревшие ответы отбрасываются по sequence/revision/target/device; ошибочная revision ответа также отклоняется. Неверная тема оставляет последнее корректное превью с явным статусом. YAML/export формирует и проверяет сервер.
Сохранение ограничено точным `site.yaml.theme.file`; разрешён отдельный относительный YAML внутри root без symlink alias/escape, не site.yaml. Если тема не настроена, используется minimal в памяти, target — theme.yaml. GET/preview не создают тему. Save получает `if_match: absent` при создании. ContentService.update_files под SiteLock перечитывает/проверяет версии и путь, валидирует весь документ, сохраняет историю и атомарно пишет файл. При первом Save также сохраняется ссылка в site.yaml с проверкой его версии. Все версии/валидация проверяются до записи; обычный отказ второго файла восстанавливает первый. Несколько rename не являются общей crash-atomic транзакцией: аварийное завершение процесса между ними может оставить несвязанный theme.yaml, который не применяется до появления ссылки. Настроенная тема сохраняется одним файлом.
409 возвращает `error.current: ThemeSnapshot`. UI оставляет пользовательские значения и предлагает принять новую основу либо явно загрузить серверную тему. Принятие основы само не пишет файл; повторный Save снова проверяет ETag. 5xx/сеть/401/403 видимы с code/message/request_id. Сбой аудита или workflow после успешной записи возвращает 500 `theme_after_commit` с `error.committed`: UI учитывает новую версию и сообщает проблему. Неожиданные исключения логируются общей границей со стеком и request_id.
PreviewStore хранит immutable HTML и необходимые ассеты вне canonical workspace. Стенд Hero/Buttons/Cards/Typography перенесён из исходника; его CSS использует core.theme.theme_css через алиасы переменных. Фактическая страница рендерится штатным Renderer с reg.theme overlay. Для стенда ассеты сайта не копируются. viewport_width передаёт только ширину окна редактора для responsive-правил оригинального стенда; числовые границы проверяются API, это не токен темы. Пассивный iframe не разрешает scripts; при настроенных разных origin действуют прежние signature/TTL/auth_epoch, CSP, nonce bridge, immutable assets. Скрипты сайта не исполняются. Текст/контролы админки не получают CSS публичной темы.
OnboardingService атомарно хранит только `{schema: 1, status}` в SITE_STATE_DIR/theme-onboarding.json под SiteLock. Без state тема в конфигурации или live-релиз означают existing; без обоих — new и redirect с обзора на setup. Текущий single-admin имеет право управления. Skip → skipped, Repeat → in_progress и первый шаг, Save → completed. Skip/Repeat не меняют тему и live; workflow переживает рестарт. Сессия не создаёт персональный мастер для каждого редактора. Повтор доступен на экране дизайна из навигации настроек.
Визуальная и функциональная приёмка — `scripts/qa_theme_manager_002.py`; серверные отказы/ETag/workflow/release — `tests/test_theme_manager.py`; отчёт — [verification-stage-5.md](verification-stage-5.md). Рабочий SITE_ROOT и live не переключались.