# حدود عمليات DOM

تدعم الإضافات التعريفية حاليًا العمليات التالية:

- `addClass`: إضافة فئة إلى العناصر المستهدفة.
- `setAttribute`: ضبط سمة.
- `setStyle`: ضبط نمط inline أو متغير CSS. أنهِ القيمة بـ `!important` لتطبيقها بتلك الأولوية؛ إذ تتجاهل إصدارات Voyager الأقدم هذه القيمة، لذا اضبط `engine` على `>=1.9.0` إذا كانت إضافتك تعتمد عليها. وتُتتبَّع الاختصارات مثل `margin` لكل خاصية فرعية على حدة، فإيقاف إضافة واحدة لا يمسح `margin-top` الخاص بإضافة أخرى.
- `hide`: إخفاء العناصر المستهدفة.

يمكن أن يكون الهدف محدد CSS أو أحد المفاتيح الدلالية المذكورة أعلاه مكتوبًا هكذا: `{ "kind": "semantic", "key": "userTurn" }`. المفاتيح الدلالية غالبًا أكثر ثباتًا، لكنها تتطلب أن يعلن محول الموقع الحالي هذا المفتاح.

يجب أن تكون العمليات التعريفية قابلة للتراجع وآمنة عند تكرار تنفيذها. لا تعتمد على حالة صفحة لمرة واحدة، ولا تفترض أن DOM لن يتغير.

## البدائيات (Primitives)

بعض السلوكيات لا يمكن وصفها بـ CSS أو بعمليات DOM القابلة للتراجع. البدائية (primitive) هي شيفرة من الطرف الأول تُشحن داخل Voyager، ويستطيع الـ manifest استدعاءها بالاسم عبر عملية `native`:

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

يختار الـ manifest بدائية ويضبط إعداداتها فقط، ولا يقدّم أي منطق، كما تتحقق البدائية نفسها من `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`.