# DOM 操作の範囲

現在の宣言的プラグインは次の操作をサポートします。

- `addClass`：対象要素にクラスを追加する。
- `setAttribute`：属性を設定する。
- `setStyle`：インラインスタイルまたは CSS 変数を設定する。値の末尾に `!important` を付けると、その優先度で適用されます。古い Voyager はこの値を捨てるため、プラグインがこれに依存する場合は `engine` を `>=1.9.0` にしてください。`margin` などのショートハンドはロングハンドごとに追跡されるので、あるプラグインをオフにしても別のプラグインの `margin-top` が消えることはありません。
- `hide`：対象要素を非表示にする。

対象は CSS セレクタ、または上のリストにある意味的キーを `{ "kind": "semantic", "key": "userTurn" }` と書いて指定できます。意味的キーはより安定しますが、対象サイトのアダプタがそのキーを宣言している必要があります。

宣言的操作は、取り消し可能で、何度実行しても安全である必要があります。一度きりのページ状態に依存せず、DOM が永遠に変わらないとも仮定しないでください。

## プリミティブ

CSS と取り消し可能な DOM 変更だけでは表現できない挙動もあります。プリミティブは Voyager に同梱されるファーストパーティのコードで、manifest は `native` 操作から名前で呼び出せます。

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

manifest はプリミティブを選んで設定するだけで、ロジックは持ちません。`params` は実行前にそのプリミティブ自身が検証します。

プリミティブを使うプラグインには 2 つのルールがあります。

- プラグインがマッチするすべてのサイトが、そのプリミティブが読むセマンティックキーを宣言していること（たとえば `mermaid` は `assistantTurn` と `codeBlock` を読みます）。`requires.handlers` は省略できます。`native` 操作がすでにそのプリミティブを示しているためです。
- `engine` は、そのプリミティブが最初に入ったエンジンバージョン以上にすること。`formulaCopy` はエンジン 1.3.0 で入ったので、使うプラグインは `">=1.3.0"` と書きます。これより低いと `bun run catalog:build` が失敗します。古い Voyager では、更新を促す代わりに handler が見つからないと報告されてしまうためです。

プリミティブは増えるだけです。新しいパラメータは必ず任意で、互換性を壊す変更は新しい名前で追加されます。

挙動が変わったプラグインは 1 行の `changelog` を付けることもできます。popup がバージョンの隣に表示します。翻訳は `name` や `description` と並べて `i18n.<locale>.changelog` に書きます。