---
name: run-al-alwah
description: Build, run, smoke-test and screenshot the الأَلْواح (AL-ALWAH) 3D browser game. Use when asked to run, start, launch, serve, build, typecheck, smoke-test, screenshot, or visually verify the game or its world/gate rendering.
---

# تشغيل الأَلْواح

لعبة متصفح ثلاثية الأبعاد (Vite + TypeScript + Three.js). لا خادم خلفي، لا قاعدة بيانات، لا مفاتيح.

**كل المسارات نسبية لجذر المستودع** (المجلد الذي فيه `package.json`).

القيادة تتم عبر `.claude/skills/run-al-alwah/driver.mjs` — سكربت Node بلا تبعيات يشغّل الخادم، يتتبّع شجرة الوحدات، ويؤكّد أن العالم يُحمَّل فعلًا، ثم يخرج برمز حالة. `npm run dev` وحده يطبع رابطًا ويتوقف إلى الأبد — لا يصلح لوكيل.

---

## ⚠️ اقرأ هذا أولًا: العالم ليس على `main`

| الفرع | ماذا يعمل |
|---|---|
| `main` | الهيكل والعقود فقط. `index.html` يحمّل `src/main.ts` وهو **هيكل فارغ**. لا عالم. |
| `agent/1-world` | **العالم كله**، عبر نقطة دخول مؤقّتة `world-dev.html`. |
| `agent/5-interface` | اللَّوح والواجهة. |

لرؤية أي شيء، اعمل على `agent/1-world`. حين يربط الوكيل ٥ العالم بـ `src/main.ts` سيصير `index.html` هو المدخل ويسقط هذا التحذير.

---

## المتطلبات

Node 18+ (اختُبر على **v24.18.0**، npm **11.16.0**). لا شيء غيره — لا Docker ولا خادم ولا متغيّرات بيئة.

```bash
node --version
npm install
```

`npm install` يطبع تحذير `allow-scripts` عن `esbuild`. **تجاهله** — الحزم تُثبَّت وvite يعمل. لا تشغّل `npm approve-scripts` بلا داعٍ.

---

## البناء والتحقق

```bash
node .claude/skills/run-al-alwah/driver.mjs check
```

يشغّل `tsc --noEmit` ثم `vite build`. مخرَجه على `agent/1-world`:

```
── التحقق من الأنواع (tsc --noEmit)
  ✓ الأنواع سليمة

── البناء الإنتاجي (vite build)
  ✓ البناء نجح

  ⚠ حزمة الإنتاج 0.82 kB فقط — src/main.ts ما زال هيكلًا فارغًا.
    العالم يعمل عبر world-dev.html فقط حتى يربطه الوكيل ٥ بـ main.ts.
```

**هذا التحذير ليس عطلًا.** `vite build` يبني من `index.html` فقط، و`world-dev.html` خارج البناء الإنتاجي عمدًا. حزمة بحجم كيلوبايت واحد **نتيجة صحيحة** حاليًا. لا تطارد "البناء مكسور".

الأوامر الأصلية تعمل مباشرة أيضًا: `npm run typecheck` · `npm run build`.

---

## التشغيل — مسار الوكيل

### الفحص الآلي (يخرج برمز حالة)

```bash
node .claude/skills/run-al-alwah/driver.mjs smoke
```

يشغّل vite، ينتظر استجابته، يمشي في شجرة الاستيرادات ثلاث طبقات، ويؤكّد تحميل وحدات من `src/world/`. المخرَج الناجح على `agent/1-world`:

```
── فحص نقاط الدخول
  ✓ /world-dev.html → 200 (867 bytes) — لوحة اختبار العالم
     وحدات محمَّلة: 6 · منها من العالم: 5
       /src/world/dev/devEntry.ts → 200 (3844 bytes)
       /src/world/World.ts → 200 (76261 bytes)
       /src/world/gates/kahfAlSada.ts → 200 (46176 bytes)
  ✓ /index.html → 200 (582 bytes) — نقطة الدخول الرسمية
     وحدات محمَّلة: 1 · منها من العالم: 0

── النتيجة
  ✓ الفحص نجح — العالم يُحمَّل.
```

يخرج بـ `0` عند النجاح و`1` عند الفشل. أضِف `--keep` ليبقى الخادم بعد الفحص.
المنفذ الافتراضي **5173**؛ غيّره بمتغيّر البيئة `ALWAH_PORT` (مفيد إن كان لديك خادم قائم).

### خادم يبقى يعمل

```bash
node .claude/skills/run-al-alwah/driver.mjs serve
```

يطبع الروابط ويبقى. أوقفه بـ Ctrl+C — يقتل شجرة العمليات كاملة (`taskkill /T` على ويندوز).

### التحقق البصري (لقطة شاشة)

**لا يوجد `chromium-cli` ولا Playwright مثبّتان.** أداة اللقطة هنا هي **لوحة المتصفح** المدمجة:

```
preview_start  { url: "http://127.0.0.1:5173/world-dev.html" }
computer       { action: "screenshot" }
```

للتحقق من الميزة الأهم — تنفيذ الآثار المُمَسرَح — اضغط زر **«اثنا عشر عمودًا»** أعلى اللوحة ثم صوّر مجددًا. النجاح يظهر كنص **«تمّ 12 أثرًا»** أسفل اللوحة، وأعمدة حجرية جديدة تصاعدت من الرمل.

أزرار لوحة الاختبار: `اثنا عشر عمودًا` · `شبكة ٥×٥` · `ارفع الأرض` · `امدد جسرًا` · `ضوء يمشي` · `افتح البوّابة` · `حلقة هاربة (٥٠٠٠)` · `أوقف` · `رجوع`.

**زر «حلقة هاربة» هو اختبار الأمان:** يرسل ٥٠٠٠ أثر؛ المتوقّع تنفيذ ٢٠٠ ثم توقّف بلا تجميد المتصفح.

---

## التشغيل — مسار الإنسان

```bash
npm run dev
```

ثم افتح `http://localhost:5173/world-dev.html` يدويًا. التحكّم: **اسحب بالفأرة** للنظر، **WASD** للمشي.

---

## الاختبارات

**لا توجد اختبارات بعد.** `npm run test` يستدعي `vitest run` وسيفشل لعدم وجود ملفات اختبار. المرشّحون الأوائل حسب الوكيل ١: `staggerFor`، سقف الآثار، وشكل التضاريس بعد `resetGate()`.

---

## مزالق

- **`index.html` يبدو معطوبًا وهو ليس كذلك.** يحمّل هيكلًا فارغًا. المدخل الحقيقي `world-dev.html` حتى إشعار آخر.
- **حجم الوحدة لا يثبت وجود العالم.** `/@vite/client` وحده ١٣٧ كيلوبايت ويُحمَّل على أي صفحة، بما فيها صفحة فارغة تمامًا. لهذا يتجاهله المشغّل ويبحث تحديدًا عن `/src/world/`. لا تحكم بالحجم.
- **لا تصادم.** اللاعب يمشي عبر الحجر. ليس عطلًا — لم يُنفَّذ بعد.
- **خادمان بواجهتَي WebGL معًا يعلّقان لوحة المتصفح.** إن تجمّدت `computer{screenshot}` مرتين متتاليتين، أوقف خوادم vite الأخرى وأعد التنقّل بـ `navigate{force:true}` على نفس التبويب. تشغيل نسختين من العالم في آن واحد هو السبب.
- **`npm install` يحذّر من `allow-scripts` بخصوص esbuild.** حميد. الحزم تُثبَّت وvite يبني.
- **PowerShell يغلّف تحذيرات stderr من العمليات الأصلية كأخطاء** (`NativeCommandError`). هذا شكل عرض لا فشل — احكم برمز الخروج لا بلون النص.
- **`package-lock.json` غير متتبَّع عمدًا** — تثبيت التبعيات ملك الوكيل ٥ حسب حدود الملكية.

---

## حلّ المشكلات

| العرض | العلاج |
|---|---|
| `لا يوجد package.json هنا` | شغّل المشغّل من جذر المستودع لا من مجلد المهارة. |
| `node_modules غير موجود` | `npm install` |
| `لم تُحمَّل أي وحدة من src/world` | أنت على `main`. انتقل إلى `agent/1-world`. |
| `لم يستجب الخادم خلال ٦٠ ثانية` | المنفذ مشغول. `$env:ALWAH_PORT=5199` ثم أعد. |
| `computer{screenshot}` ينتهي بمهلة | أوقف خوادم vite الأخرى، ثم `navigate{force:true}`. |
| `vitest` يفشل بـ "no test files" | متوقّع — لا اختبارات بعد. |