# План 002 — Site Studio и Theme Manager Дата: 2026-11-13. Основание — [спецификация](spec.md), выполнение — [задачи](tasks.md), проверка текущего этапа — [verification.md](verification.md). Этапы 4 и 5 выполнены последовательно по отдельным поручениям пользователя. Этап 4 принят; приёмка Theme Manager — отдельный шаг. Этапы 2 и 3 взяты и выполнены вместе по прямому поручению пользователя. Их совместная приёмка — [verification-stages-2-3.md](verification-stages-2-3.md); переход к этапу 4 остаётся отдельным решением. ## Архитектурные решения - Каталог обнаруживает манифесты рекурсивно; идентичность фрагмента и категория — разные свойства. Сохранены глобальные ID и запрет затенения builtin. - Категория пути вычисляется в registry. API остаётся проекцией ядра; русские подписи и объединение прежних категорий относятся только к HTML-представлению. - Файловый theme.yaml — единственный реализованный формат темы с этапа 2. Это выбранное пользователем решение, без инфраструктуры миграции; прежний inline runtime отклоняется диагностикой. - Валидация/разрешение темы и ширины живут в ядре с dataclass. API использует Pydantic DTO, вызывает сервисы вне event loop и сохраняет существующие обработчики ошибок. Предпросмотр, CLI и build используют один resolver. - Theme Manager переносится из исходников Antirion. Моки и localStorage заменяются API; новый интерфейс и независимые frontend-алгоритмы темы не создаются. - Каждая стадия готовится отдельно для пользовательской приёмки. Запуск проекта с новым SITE_ROOT и коммиты examples в этот план не входят. ## Этап 1 — Категории и каталог (реализован, ожидает приёмки) 1. В загрузчике вычислить категорию из первого каталога для вложенного размещения, сохранив плоскую структуру и рекурсивный поиск. 2. Загрузить optional preview.yaml, проверить envelope/props, объединить поверх inline preview по ключам, оставить плоскую форму API. 3. Перенести 15 builtin по категориям, изменить только category в манифестах. Сверить ID и байты шаблонов/ресурсов. 4. Показать категории в существующем каталоге, добавить поиск по коду и подписи, объединить legacy labels, сохранить описание/allow/ID. Синхронизировать фильтр после HTML swap. 5. Проверить смешанный сайт и реальный путь login → HTML → внутренний API → transform/preview/save. Повреждённый preview должен быть виден в workspace/publish, отказ не меняет live. 6. Проверить wheel вне checkout, браузер desktop/mobile и регрессии; обновить AGENTS/README и отчёт. Выход: действующие сайты используют прежние ссылки на фрагменты; пользователь видит категории в добавлении блока. Ни тема, ни оформление публичных фрагментов на этой стадии не меняются. ## Этап 2 — Ядро файловой темы и публикация (реализован, ожидает приёмки) 1. Добавить dataclass-модель ThemeDocument/EffectiveTheme, валидатор и каталог immutable preset@version в runtime-пакете. Перенести значения и разрешённые шрифты из дизайн-JS, зафиксировать диапазоны из spec. 2. Site читает theme.file; registry разрешает документ и добавляет диагностику в общий Report. Отсутствующая настройка использует minimal@1 в памяти; явная плохая ссылка и legacy tokens дают ошибку. 3. Обновить конфигурации примеров/фикстур в исходниках под theme.yaml. Сохранять цвета существующих примеров через новые семантические/custom токены, не переписывая их страницы. 4. Подключить effective tokens к bundle и preview через общий renderer. Токены применяются после defaults; CSS-потребители builtin используют согласованную таблицу переменных. Не менять палитру админки. 5. Дополнить manifest релиза разрешённой темой и preset/version. Учитывать theme/preset/render resources при fingerprint; не перезаписывать исторический релиз другим результатом. Сохранять атомарный current и независимость rollback от workspace. 6. Проверить воспроизводимость, все preset/Custom, контраст-warning, недопустимый ввод, сохранность старого live при ошибке и правильную тему после rollback. Набор пресетов и данные темы должны попадать в wheel. Выход: CLI/build/preview читают один новый контракт и одинаково формируют оформление. API/UI управления темой добавляются на этапе 5. ## Этап 3 — Ширина сайта и блока (реализован, ожидает приёмки) 1. Добавить BlockLayout в модель, разрешённые ключи YAML, общий валидатор и resolver наследования. Явно проверить объекты и enum; числовой legacy container не включать. 2. Передать layout через снимки, существующие операции блока, API DTO, формы и parse/serialize. Метаданные не должны теряться при редактировании props, добавлении, дублировании и переносе блока. 3. Применять ширину к собственным корням и контейнерам фрагмента, исключая утечку правил в nested blocks. Сохранить sticky-header, anchors, slots и preview markers без нарушающих геометрию wrappers. 4. Перенести контролы ширины инспектора из обновлённого дизайна и связать с transform. Обновление preview асинхронное; сохранить выделение/scroll и локальный выбор секции. 5. Проверить global modes, пары внешней/внутренней ширины, responsive gutters и границы 699/700/1023/1024 px. Сверить Конструктор ↔ Эксперт, fixed/Display/slots и отсутствие overflow на 360 px. Выход: штатный renderer и конструктор понимают layout из нового примера. ## Этап 4 — Общие компоненты и examples/site-studio 1. Сопоставить seed и текущие полноценные схемы по ST-01/02. Сохранить ID и проверенные названия/описания, перенести HTML/CSS компонентов из источника. 2. Добавить builtin content/steps с title/items, исключив локальный дубликат ai-studio в том же обновлении исходников. Сохранить поддержку прежнего card_grid.variant: steps. 3. Добавить data/entry_card и универсальный ref `to: '*'`, value collection/slug: парсинг, валидация, resolver, выбор в формах, проверки published target. Фиксированные ref/refs не изменяются. 4. Дополнить entry_header и form необязательными полями из spec. Перенести общие стили, связывая литералы дизайна с effective tokens, сохраняя исходное оформление при значениях seed. 5. Создать новый examples/site-studio: данные/ассеты из seed, адаптированные Page/Entry/Collection/Display/Menu/Form/Redirect, layouts с engine hooks. Не копировать повторные builtin manifests или mini-renderer. 6. Описать запуск отдельно от рабочего сайта. Проверить 13 опубликованных страниц, отсутствие draft booking в live, ссылки/ассеты/редиректы, формы без ложного успеха, отключённые коллекции и совместимость прежних примеров. 7. Проверить публичные страницы и общие компоненты относительно design preview на desktop/mobile. Документировать различия из-за данных и штатных SEO/assets hooks; не заменять визуальную проверку HTTP 200. Выход: отдельный пример проходит стандартный validate/build, общие компоненты сохраняют функциональные возможности. ## Этап 5 — ThemeService, Theme Manager и onboarding 1. ThemeService предоставляет get/list_presets/resolve/validate/save; OnboardingService — status/skip/restart. Подключить JSON и HTML endpoints из API-01 без обходов внутреннего API. 2. API DTO: ThemeSnapshot, ThemeUpdate, ThemePreviewRequest, ThemeDiagnostics, OnboardingState. Snapshot содержит document/etag/effective_tokens/diagnostics/workspace_revision/live_build_id; ErrorEnvelope допускает текущий снимок темы при 409. If-match для создания — ABSENT. 3. Save проходит через ContentService с точным разрешённым путём, SiteLock, CAS, проверку, историю, atomic write и аудит. Изменения после Save не публикуются. Конфликт и 5xx сохраняют пользовательский ввод; неожиданные ошибки коррелируются через request_id. 4. Расширить существующий PreviewStore overlay темы без сохранения файлов сайта, сохранив CSP/origin/nonce/immutable snapshots. Стенд из дизайн-макета и фактическая страница используют один token resolver; ответы связаны с revision. 5. Перенести исходные HTML/CSS/JS Theme Manager в существующий Antirion shell. Подключить четыре шага, reset/skip/repeat, YAML/export, диагностику, desktop/mobile и ссылки настройки. Сохранять рабочее состояние вкладки до явного Save; не переносить auto-localStorage или beforeunload. 6. Состояние мастера хранить атомарно в SITE_STATE_DIR/theme-onboarding.json под блокировкой сайта; в нём нет canonical palette. Инициализацию различать по наличию настроенной темы/релиза, текущему admin разрешить как владельцу. Save завершает workflow, skip/restart независимы от live. 7. Выполнить серверные проверки ETag/CSRF/доступа, сбои диска/аудита/сети, два одновременных редактора, рестарт, существующий/новый сайт, skip/repeat, publish/rollback и отсутствие потери правок. Выход: экран из дизайна управляет настоящим файлом и превью, существующая публикация остаётся отдельным действием. ## Общая проверка и передача этапов После каждого функционального этапа: целевые unit/integration checks → штатные validate/build → реальный FastAPI и browser → installed wheel для новых ресурсов → отчёт с ограничениями → пользовательская приёмка. Для нового Theme Manager обязательна сверка с оригиналом на 1440/1280/1024/768/390/360 px, клавиатура и фокус, отсутствие native dialogs, JS/CSP/HTTP-ошибок, горизонтального переполнения и изменения skin админки. Для общих компонентов повторить проверки старых примеров и функциональности больше трёх steps/items. Пользовательские изменения examples/studio-site/pages/index.md не исправляются ради тестов. При необходимости базовая фикстура извлекается из HEAD во временный каталог; отчёт явно отличает такую регрессию от проверки текущего пользовательского сайта. Изменения runtime требуют пересборки образа. Root examples не коммитятся, рабочий SITE_ROOT не переключается, live не публикуется автоматически. Завершение всей 002 отмечается только после выполнения и приёмки всех этапов.