# Руководство по участию в разработке плагинов

Система плагинов Voyager в первую очередь рассчитана на декларативные плагины: `plugin.json` описывает метаданные и DOM-операции, а CSS описывает визуальные изменения. Сам плагин не выполняет удаленный JavaScript; встроенный движок Voyager интерпретирует manifest и стили.

Так плагины проще проверять и поддерживать. Если вы хотите предложить плагин, начните с этого подхода.

## Рекомендуемый путь

1. Сначала убедитесь, что идея подходит для плагина: ширина чтения, исправления верстки, настройки темы, скрытие или пометка элементов страницы, простая адаптация сайтов обычно подходят.
2. Сначала откройте Issue или PR в основном репозитории Voyager. Опишите проблему, целевой сайт и отличие от существующих плагинов.
3. Используйте `plugin.json` для метаданных, соответствий сайтам, настроек и вкладов.
4. Поместите стили в `style.css` в том же каталоге и подключите его через `contributes.styles`.
5. Протестируйте локально и приложите к PR тестовые страницы, скриншоты или короткую запись. Мейнтейнеры решат, готов ли плагин для официального catalog.

## Границы плагина

Плагин должен ограничиваться пользовательской задачей, а не механически делиться по платформам.

Если одна функция дает почти одинаковый опыт и настройки на нескольких платформах, лучше сделать один кросс-платформенный плагин. Например, ширина чтения, навигация по страницам или оформление блоков кода могут покрывать Claude, ChatGPT и другие сайты через несколько `matches`.

Если для каждой платформы нужны совершенно разные настройки, DOM-логика или пользовательские тексты, отдельные плагины будут понятнее. Не помещайте несвязанные функции в один плагин только ради "один плагин для всего"; один плагин должен решать одну понятную задачу.

Короткое правило:

- Одна пользовательская цель, одинаковые настройки, отличаются только селекторы: предпочитайте один плагин.
- Одна тема, но опыт сильно различается по платформам: можно разделить, сохранив связь в названиях и описаниях.
- Разные цели: не объединяйте.

## Избегайте дубликатов

Перед отправкой проверьте marketplace и существующие официальные плагины. Если хороший плагин уже есть, лучше улучшить его, чем создавать похожий.

Дубликат стоит принимать только при явном улучшении, например:

- Он поддерживает важную платформу, которую не покрывает исходный плагин.
- Он исправляет проблему совместимости, которую исходный плагин не может решить.
- Он заметно лучше по производительности, доступности или поддерживаемости.
- Он предлагает действительно другой полезный пользовательский опыт, а не только новое имя или легкие изменения стилей.

Так marketplace остается чище, а пользователям легче выбирать.

## Минимальный пример

```json
{
  "id": "your-name.example-plugin",
  "name": "Example Plugin",
  "version": "1.0.0",
  "description": "A short description of what this plugin improves.",
  "author": "your-name",
  "category": "readability",
  "license": "MIT",
  "engine": ">=1.0.0",
  "tier": "declarative",
  "matches": ["https://claude.ai/*"],
  "contributes": {
    "styles": [{ "file": "style.css" }],
    "domOps": [
      {
        "op": "addClass",
        "target": "body",
        "className": "gv-plugin-example"
      }
    ]
  }
}
```

`style.css` можно писать как обычный CSS, но стили плагина лучше держать внутри собственной `gv-plugin-*`-класса:

```css
.gv-plugin-example .some-target {
  max-width: 880px;
}
```

## Заметки по manifest

- Для `id` используйте префикс автора или стиль обратного домена, например `your-name.reading-width`, чтобы избежать конфликтов.
- Держите `matches` узкими. Указывайте только сайты, где плагин действительно должен работать.
- Один плагин может содержать несколько `matches`, если эти платформы имеют одну ясную функциональную цель.
- Рекомендуемые значения `category`: `render-fix`, `theme`, `layout`, `readability`, `productivity`, `integration` или `other`.
- В `engine` укажите требуемую версию движка плагинов. Официальные плагины можно использовать как пример.
- По возможности добавьте `i18n` для китайского, английского и других распространенных языков.

## Ограничения CSS и ресурсов

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

- Не используйте `@import`.
- Не ссылайтесь на удаленные изображения, внешние шрифты или удаленный CSS.
- Можно использовать обычный CSS, пользовательские свойства и подстановки значений настроек Voyager.
- Используйте префикс `gv-plugin-` для классов, чтобы не загрязнять стили сайта или самого Voyager.

Если плагину нужны настройки, по возможности начните с числовых значений. Например, плагин ширины чтения может записывать значение настройки в CSS-переменную, а CSS будет ее использовать.

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

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

- `addClass`: добавить класс целевым элементам.
- `setAttribute`: установить атрибут.
- `setStyle`: установить inline-стиль или CSS-переменную.
- `hide`: скрыть целевые элементы.

Целью может быть CSS-селектор или семантический селектор, предоставленный адаптерами сайтов Voyager. Семантические селекторы обычно стабильнее, но требуют поддержки в адаптере текущего сайта.

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

## Когда обычный плагин не подходит

Если функции нужно выполнять JavaScript, перехватывать запросы, читать или записывать внутренние данные Voyager, либо полагаться на сложную runtime-логику, она не подходит для обычного декларативного плагина.

Сначала откройте Issue и опишите потребность. Если действительно нужна встроенная возможность, мы можем рассмотреть реализацию в репозитории Voyager как builtin/native-плагин, например Formula Copy.

## Перед открытием PR

- Плагин выключен по умолчанию, пользователь включает его сам.
- Вы проверили, что почти такого же плагина нет; если есть, сначала улучшили существующий.
- Вы протестировали целевой сайт в светлой и темной теме.
- `matches` не охватывает несвязанные сайты.
- Нет ссылок на удаленные ресурсы.
- Каталог плагина содержит `plugin.json`, необходимые CSS-файлы и короткий README.
- PR описывает тестовые страницы, скриншоты или записи, а также затронутые области страницы.

Держите плагин простым, сфокусированным и обратимым. Плагин, решающий одну ясную задачу, гораздо проще принять и поддерживать.