# Границы DOM-операций

Декларативные плагины сейчас поддерживают:

- `addClass`: добавить класс целевым элементам.
- `setAttribute`: установить атрибут.
- `setStyle`: задать inline-стиль или CSS-переменную. Если значение заканчивается на `!important`, оно применяется с этим приоритетом; старые версии Voyager такое значение отбрасывают, поэтому, если плагин на это полагается, укажите `engine` как `>=1.9.0`. Сокращённые свойства, например `margin`, отслеживаются по каждому longhand-свойству, поэтому выключение одного плагина никогда не сбрасывает `margin-top` другого плагина.
- `hide`: скрыть целевые элементы.

Целью может быть CSS-селектор или один из перечисленных выше семантических ключей, записанный как `{ "kind": "semantic", "key": "userTurn" }`. Семантические ключи обычно стабильнее, но адаптер текущего сайта должен объявлять этот ключ.

Декларативные операции должны быть обратимыми и безопасными при повторном выполнении. Не зависьте от одноразового состояния страницы и не предполагайте, что DOM никогда не меняется.

## Примитивы

Некоторое поведение нельзя описать через CSS и обратимое изменение DOM. Примитив представляет собой собственный код, который поставляется внутри Voyager; манифест может вызвать его по имени через операцию `native`:

```json
{
  "engine": ">=1.3.0",
  "requires": { "handlers": ["formulaCopy"] },
  "contributes": {
    "domOps": [{ "op": "native", "handler": "formulaCopy", "params": {} }]
  }
}
```

Манифест выбирает примитив и настраивает его, но никогда не задаёт логику, а `params` проверяет сам примитив перед запуском.

Для любого плагина, который использует примитив, действуют два правила:

- Каждый сайт, на который нацелен плагин, должен объявлять семантические ключи, которые читает примитив (например, `mermaid` читает `assistantTurn` и `codeBlock`). `requires.handlers` необязателен: операция `native` уже подразумевает свой примитив.
- `engine` должен быть не ниже той версии движка, в которой примитив появился. `formulaCopy` появился в движке 1.3.0, поэтому использующий его плагин объявляет `">=1.3.0"`. Более низкий диапазон приводит к ошибке `bun run catalog:build`, потому что старая версия Voyager сообщила бы о недостающем handler вместо предложения обновиться.

Примитивы только дополняются: новый параметр всегда необязательный, а несовместимое изменение выходит под новым именем.

Плагин с изменившимся поведением может нести однострочный `changelog`, который popup показывает рядом с версией. Перевод пишется в `i18n.<locale>.changelog` рядом с `name` и `description`.