# فنّ المجسّمات — دليل رِماية (v3)

> PROTOTYPE. هذا هو المرجع الملزم لصناعة **المجموعة القياسية** من مجسّمات رِماية.
> **v3 يغيّر شيئين جوهريين عن v2:**
> 1. **رفع تصاميم من المتاجر خارج النطاق.** لا يوجد رفع SVG ولا ZIP في هذه النسخة.
>    المتجر **يختار** من مجموعة قياسية (10 مجسّمات) — لا يرفع شيئًا.
> 2. **لا مواضع.** العروض تظهر في **كل الصفحات** بنفس الترتيب الذي يحدده التاجر.
>
> freedoms الباقية كما هي: **لا لوحة، ولا خلفية، ولا حدود، ولا حجم مفروض** —
> الملف يملك الشكل والحجم وحالة الرسم، والمستضيف يملك التفاعل فقط.

## القاعدة الأولى: الحرية

- **لا خلفية، لا إطار، لا حدود، لا ظلّ من طرفنا.** الرسم يطفو حرًا فوق أي صفحة.
- الشكل حر: مربّع، مستطيل، غير منتظم — كما يشاء المصمم.
- **الحجم من الملف**: `display.width` هو العرض الأساسي، والارتفاع يتبع نسبة الرسم.
- يجب أن يُقرأ الرسم فوق صفحة بيضاء، وداكنة، وصور حقيقية.

## المجموعة القياسية (10)

| id | الاسم | المتجر المقصود |
| --- | --- | --- |
| `island` | جزيرة الصيف | عام / متاجر صيفية |
| `watch` | ساعة | ساعات وإكسسوارات |
| `handbag` | حقيبة أنيقة | أزياء وحقائب |
| `backpack` | حقيبة المدرسة | أطفال ودراسة |
| `coffee` | كوب قهوة | قهوة ومقاهي |
| `basket` | سلة تسوّق | بقالة ومواد غذائية |
| `dates` | علبة تمر | تمور وعسل وسلال |
| `gift` | علبة هدية | هدايا وزهور |
| `sneaker` | حذاء رياضي | أحذية ورياضة |
| `headphones` | سماعة رأس | إلكترونيات |

## الحالات المتفق عليها

| الحالة | متى تُعرض | الدور من الفن |
| --- | --- | --- |
| `idle` | لا تقدّم بعد | حلقة هادئة دائمة: ≥3 عناصر بأطوار وأزمنة مختلفة |
| `progress` | بدأ العميل | إشارة تقدّم واضحة (يمتلئ / يتقدّم / يقترب) |
| `ready` | بقيت قطعة واحدة | توتّر لطيف: توهّج استعداد ولمعة |
| `done` | اكتمل الكل | احتفال قصير ثم هدوء راضٍ |
| `peek` | تنبيه لمرة واحدة | حركة لفت انتباه (1.2–1.8s) فوق أي حالة |

**ممنوع**: وميض أسرع من 3Hz، اهتزاز مزعج، دوران مستمر كامل.

## حزمة الفن (داخلية)

```text
mascots/<id>/
├── manifest.json     البطاقة (داخلية — تُولَّد js/mascots.js)
├── mascot.svg        كل الحالات في ملف واحد
└── shots/            لقطات التحقق
```

```json
{
  "id": "island",
  "name": "جزيرة الصيف",
  "name_en": "Summer Island",
  "hint": "رمل ومظلّة وبحر",
  "version": "3.0.0",
  "art": "mascot.svg",
  "display": { "width": 92, "min": 56, "max": 128 },
  "states": ["idle", "progress", "ready", "done", "peek"],
  "themable": ["--w-accent"],
  "status": "standard"
}
```

## قواعد ملف SVG

1. الجذر:
   `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" data-art="<id>" aria-hidden="true" focusable="false" role="presentation">`
2. **خلفية شفافة إلزاميًا** — لا شكل يغطي الكانفس.
3. كل الأنماط داخل `<style>`، وكل مُحدِّد محصور تحت `[data-art="<id>"]`.
4. كل المعرّفات تبدأ ببادئة المجسّم (`isl-`, `cof-`, `bsk-`, `dts-`, `gft-`, `snk-`, `hph-`).
5. **ظهور الحالات عبر الخصائص فقط** (مهم: اللقطات تُلتقط بحركة مجمّدة):
   - `[data-state="progress"] [data-art="x"] .m-progress { … }` (وكذلك ready/done)
   - `[data-peek="true"] [data-art="x"] .m-peek { … }`
   المستضيف يضع `data-state` و`data-peek` على غلاف `.w-mascot`.
   **لا تعتمد على `animation` لإظهار طبقة حالة** — اجعل الظهور قاعدة CSS.
6. **ممنوع**: `script`، مراجع خارجية (`<image>`, `@import`, `url(http…)`)، خطوط،
   `<text>` بخط ويب، `foreignObject`. الحركة على `transform`/`opacity` فقط.
7. دورات الحركة الأبدية 2.5–7s · انتقالات وظيفية 160–600ms · عناصر متحركة ≤25.
8. الحجم ≤120KB (الهدف ≤60KB).
9. `@media (prefers-reduced-motion: reduce)` داخل الملف: تجميد كامل بإطار ثابت جميل لكل حالة.
10. **الملف يجب أن يكون XML صالحًا** (اختبار: `try { $null = [xml](Get-Content mascot.svg -Raw); "VALID" } catch { "INVALID" }`).

## المعاينة والتحقق

من جذر المستودع: `python -m http.server 8123`

```text
http://localhost:8123/prototypes/pocket/mascots-lab.html?grid=states&size=76&bg=paper&pause=1
http://localhost:8123/prototypes/pocket/mascots-lab.html?shot=1&art=coffee&state=done&size=128&bg=dark&pause=1
```

- `shot=1` لقطة نظيفة لمجسّم واحد · `state=` · `size=` 56–160 · `bg=` canvas|paper|dark|store|checker
- `pause=1` يجمّد الحركة (لقطات حتمية) · `grid=states` مصفوفة كل الحالات.

> **feature الصيانة:** رُفعت واجهة تجربة الرفع من المختبر (خارج النطاق في v3).

## قائمة الجودة — شرط القبول

- [ ] ظلّ يُقرأ فورًا عند 56px ويُبهر عند 128px.
- [ ] ≥3 حركات مستقلة في `idle` بأطوار مختلفة.
- [ ] الحالات الخمس مميزة في لقطة واحدة مجمّدة.
- [ ] لا قصّ، ولا خروج عن `viewBox`.
- [ ] يُقرأ على أبيض/داكن/مزدحم بلا خلفية.
- [ ] إطار ثابت جميل مع `prefers-reduced-motion`.
- [ ] XML صالح، بلا نصوص، بلا مراجع خارجية، ≤120KB.
- [ ] هادئ — لا يسرق الانتباه أثناء التسوّق.