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

22 KiB
Raw Permalink Blame History

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 не переключались.