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.
22 KiB
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 в памяти, файл не создаётся.
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 блока и конструктор
- 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 сохраняются.
Проверка и запуск
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 не коммитятся. Проверки и артефакты — в отчёте.
Этап 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. Рабочие 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. Рабочий SITE_ROOT и live не переключались.