عن المشروع

## نظرة عامة @missing-elements/h5p-offline-player هو مكوّن ويب (`<h5p-player>`) يشغّل ملفات أرشيف `.h5p` عشوائية بالكامل داخل المتصفح. لا حاجة إلى خادم خلفي، ولا فك ضغط على الخادم، ولا خطوة استخراج مسبقة. يمكن للمكوّن تحميل الحزم من رابط URL أو من ملف محلي يتم اختياره عبر منتقي الملفات. يُوزَّع المشغل كوحدة ES module إلى جانب نص Service Worker ومجلد من أصول وقت تشغيل H5P. وهو يعمل مع أدوات التجميع مثل Vite وwebpack 5 وRollup، أو يمكن استخدامه مباشرة من CDN دون خطوة بناء. يجب تقديم Service Worker من نفس الأصل (origin) الخاص بصفحة الاستضافة؛ أما أصول الإطار فقد تأتي من CDN. ## كيف يعمل ملف `.h5p` هو أرشيف zip. وبدلاً من أن يقوم خادم بفك ضغطه، يقرأ Service Worker الأرشيف في مكانه ويقدّم طلبات وقت تشغيل H5P من داخله: - يُقرأ الدليل المركزي للأرشيف عبر طلبات HTTP Range، لذا تبدأ الحزم الكبيرة بسرعة مع نقل بيانات أولي ضئيل. - تُجلب نطاقات البايتات الكبيرة عبر عدة اتصالات متوازية وتُعاد تجميعها بالترتيب، ما يحسّن بدء التشغيل على الروابط البطيئة. - تُفك ضغط المدخلات الصغيرة والنصوص البرمجية مرة واحدة إلى مخزن Cache API. - تُقطَّع الوسائط الكبيرة المخزّنة مباشرة من الأرشيف دون استخراج. - تُفك ضغط الوسائط الكبيرة المضغوطة (deflated) على شكل أجزاء بحجم 8 ميغابايت بواسطة عامل (worker) في جانب الصفحة وتُقدَّم تدريجياً، بحيث يمكن أن يبدأ تشغيل الفيديو قبل اكتمال الاستخراج الكامل. - يُولَّد مستند الإطار بواسطة العامل مع سياسة أمان محتوى (Content Security Policy) لكل استجابة. تُعالَج المضيفات التي لا تدعم Range بتنزيل الأرشيف بالكامل إلى مخزن الأجزاء، مع فهرسته من الترويسات المحلية أثناء وصوله، بحيث يمكن للحزم المرتّبة بحيث تأتي المكتبات أولاً أن تُقلع بينما لا تزال الوسائط قيد التنزيل. ## أبرز ملامح واجهة البرمجة (API) - **`src`** — سمة/خاصية لرابط URL الخاص بالحزمة؛ تعيينها يؤدي إلى التحميل، مثل `<video>`. - **`file`** — خاصية تقبل كائن `File` للتشغيل من القرص دون شبكة. - **`sw`** — سمة لرابط URL الخاص بـ Service Worker (يجب أن يكون من نفس الأصل). - **`assets-base`** — سمة لمجلد أصول الإطار (يمكن أن يكون CDN). - **`libraries`** — سمة لتحميل مجلدات المكتبات من hub أو حزمة مجمّعة. - **`resume`** — سمة لحفظ حالة المتعلّم على الجهاز أو تسليمها إلى صفحة الاستضافة. - **`preload`** — سمة لجلب الوسائط الكبيرة المضغوطة مسبقاً قبل طلبها. تشمل الخصائص للقراءة فقط `state` (idle، probing، downloading، indexing، ready، error)، و`pkgId`، و`revision`، و`scope`. ## الأحداث يُصدر العنصر أحداث `ready`، و`xapi` (لبيانات xAPI الصادرة من المحتوى)، و`finished` (الإكمال مع النتيجة)، و`userdata` (الحالة المحفوظة)، و`progress` (مراحل التنزيل/الفهرسة)، و`resize`، و`statechange`، و`error`. بيانات xAPI هي القناة الوحيدة للنتائج ولا يخزّنها المشغل نفسه أبداً. ## ميزات إضافية - **دعم PWA**: تطبيق قابل للتثبيت ويعمل دون اتصال لمتصفحي Chrome/Edge. - **تكامل cmi5**: متاح كـ `@missing-elements/h5p-cmi5` لوحدات assignable units التي تُطلق من نظام إدارة التعلّم (LMS). - **مهارات الوكلاء (Agent skills)**: يوفّر مهارات لـ Claude Code وCursor وCopilot وCodex تغطي الإعداد وتوحيد الحزم والتحقق. - **إمكانية الوصول**: منهج مطابقة موثّق يغطي سلوك المشغل ومسؤوليات أنواع المحتوى. - **أداة تحقق**: يشغّل `h5p-verify` الحزم بلا واجهة رسومية للتأكد من عملها. ## الترخيص كود المشغل نفسه بترخيص MIT. الحزمة المنشورة تحمل `(MIT AND GPL-3.0-only)` لأن وقت تشغيل نواة H5P المجمّع (من h5p-standalone/h5p-php-library) بترخيص GPL-3.0. نصوص Service Worker تجمّع zip.js (BSD-3-Clause). إشعارات الترخيص مضمّنة في الملفات المُصدَرة.