# Жизненный цикл темы

## 1. Создание

В Godot Editor выберите `Редактор → Создать тему`. Укажите стабильный lowercase ID с
латинскими буквами, цифрами и дефисами и человекочитаемое название. Аддон скопирует `example`,
обновит manifest и сразу активирует новую тему.

Для автоматизации можно скопировать `themes/example` в `themes/<theme-id>`. Используйте ID с
латинскими буквами, цифрами и дефисами. Измените только `ThemeId` и человекочитаемый
`DisplayName` в manifest; канонические scene keys/paths не меняйте.

## 2. Активация

В Godot Editor выберите `Редактор → Выбрать тему`. После подтверждения аддон остановит запущенный
preview при необходимости, запишет выбранный package в `build/active-theme.json`, откроет preview
и восстановит запуск.

Эквивалентная PowerShell-команда:

```powershell
.\activate-theme.ps1 -ThemeId space-pixel
```

Команда только проверяет manifest и пишет `build/active-theme.json`. Корневая копия темы не
создаётся: активный package остаётся единственным источником.

## 3. Редактирование и live reload

Источник — видимый в Godot FileSystem каталог `themes/<id>/package/`. Запущенный preview
загружает его сцены напрямую, следит за изменёнными `.tscn`, `.tres`, JSON, изображениями,
шрифтами и звуком и сохраняет выбранную вкладку при перезагрузке.

Открывайте production-сцены прямо из `res://themes/<id>/package/scenes/`. Их ссылки относительные:
каждая тема использует собственные `assets/`, `components/` и `visuals`, даже когда рядом
индексируются остальные темы. Сцена уже содержит собственные `Theme`, статический фон и
decoration, поэтому её вид в редакторе является production-видом, а не упрощённым каркасом.
Если Godot Editor пересохранил ссылку с полным builder-префиксом, временный test/build workspace
автоматически заменит его на `res://exchanger_theme_dlc/`; исходный package при этом не меняется.

## 4. Preview

```powershell
.\preview-theme.ps1 -ThemeId space-pixel
```

Верхняя панель переключает девять экранов. `BINDINGS: ON/OFF` включает подписи metadata. Overlay
нужен для проверки контракта, а финальный визуальный QA делается с выключенными подписями. Галерея
не меняет инстанцированные сцены и не добавляет им оформление или preview-only содержимое.

## 5. Проверка

```powershell
.\tools\Test-PackagedBindingContract.ps1
.\test-theme.ps1 -ThemeId space-pixel
```

Первая команда без Godot сверяет byte-identical копии контракта во всех темах. Вторая выбирает
тему, валидирует её в изолированном временном workspace и запускает headless smoke preview,
который читает исходный package напрямую.

## 6. Сборка

В Godot Editor выберите `Редактор → Экспортировать тему`, выберите любую валидную тему по ID,
затем укажите каталог и имя `.pck` в стандартном диалоге сохранения. Аддон проверит и соберёт
именно выбранную тему в фоне, не переключая preview и не заменяя установленную тему Exchanger.
Окно прогресса показывает импорт, проверку контракта, экспорт, проверку пакета и завершение.

Эквивалентная команда с путём по умолчанию:

```powershell
.\build-theme.ps1 -ThemeId space-pixel
```

Результаты: `build/space-pixel.pck` и совместимая копия `build/active_theme.pck`. Для сохранения
обязательных runtime-путей сборка кратковременно создаёт
`build/theme-workspaces/<id>-build/exchanger_theme_dlc/`, экспортирует PCK и удаляет workspace.
`build/` скрыт от Godot через собственный `.gdignore` и игнорируется системой контроля версий.
Выбор другого пути в Editor передаётся скрипту как `-OutputPath -PreserveActiveTheme`: поэтому
редакторский экспорт не меняет `build/active-theme.json` и `build/active_theme.pck`. Прямой запуск
скрипта без `-PreserveActiveTheme` сохраняет прежнее поведение и обновляет совместимую копию.

## 7. Установка

Закройте Exchanger, затем в Godot Editor выберите
`Редактор → Применить тему к Exchanger`. В компактном окне проверьте ID активной темы и путь,
нажмите `Собрать и применить`. Аддон выполняет validator, export и установку в фоновом потоке;
редактор остаётся доступен, а отдельное окно показывает текущий этап, процент и результат.

Эквивалентная команда для автоматизации:

```powershell
.\build-theme.ps1 -ThemeId space-pixel -InstallToDefaultUserPath
```

Команда заменяет `%APPDATA%\Godot\app_userdata\Exchanger\theme_dlc\active_theme.pck`. После этого
нужен полный перезапуск Exchanger и интеграционный checklist из `THEME_INTEGRATION.md`.

## 8. Изменение host-контракта

Это отдельная миграция, а не часть обычного оформления темы. Сначала изменяется Exchanger и его
тесты, затем builder синхронизируется штатной командой. Последовательность описана в
[BINDING_CONTRACT.md](BINDING_CONTRACT.md). Никогда не правьте 481 ID вручную в обход host.