Upload 8 files

QURAN_INTEGRATION.md

@@ -5,7 +5,7 @@
 
 ## الملفات
 
-تكون الملفات السبعة الآتية بجوار ملفات الساعة الحالية، بنفس الأسماء تمامًا:
+تكون الملفات التسعة الآتية بجوار ملفات الساعة الحالية، بنفس الأسماء تمامًا:
 
 | الملف | المسؤولية |
 |---|---|
@@ -14,6 +14,8 @@
 | `quran_reader.js` | التحميل، العرض، البحث، التنقل وإعدادات القراءة |
 | `quran_reader.css` | تنسيق القارئ داخل نافذة الساعة الحالية |
 | `quran_reader_registry.json` | عناوين الواجهة، إعدادات العرض ومسارات البيانات |
+| `quran_audio.js` | مشغّل التلاوة المستقل والتحكم بالصوت وأحداث التظليل |
+| `quran_audio_registry.json` | مصدر التلاوات والقرّاء وخيارات التشغيل ونصوص الواجهة |
 | `quran_core_registry.json` | السور والآيات والأجزاء والصفحات من المصدر |
 | `al_khatma_source_attribution.md` | نسبة المصدر ونص ترخيصه |
 
@@ -25,15 +27,20 @@
 
 1. اضغط على خانة ساعة، ثم «قراءة القرآن الكريم».
 2. اختر سورة أو جزءًا، أو أدخل رقم صفحة. يعرض القارئ الصفحة المرتبطة بذلك الموضع، ويحدد أول آية مطلوبة.
-3. البحث يشمل القرآن كله؛ الضغط على النتيجة يفتح صفحتها ويحدد الآية.
-4. إعدادات حجم الخط وتذكر آخر صفحة موجودة داخل إعدادات القراءة، ويمكن الوصول إليها أيضًا من إعدادات الساعة الموجودة.
-5. زر الإغلاق الموجود يغلق النافذة فقط؛ لا يسجل إتمام عبادة أو ختمة.
+3. البحث يشمل القرآن كله؛ الضغط على النتيجة يفتح صفحتها ويحدد الآية. حقل «بحث عن سورة» يرشح فهرس السور.
+4. اضغط الآية لفتح إجراءاتها: الاستماع منها أو نسخ نصها مع مرجعها. لوحة المفاتيح تعمل عبر Tab ثم Enter أو المسافة.
+5. التحكم بالصوت: تشغيل، إيقاف مؤقت، استكمال، إيقاف، الآية السابقة والتالية، وشريط تقدم قابل للتقديم والتأخير.
+6. افتح «القارئ وخيارات التلاوة» لاختيار العفاسي أو الحصري أو المنشاوي، وتغيير السرعة والتكرار والمتابعة التلقائية.
+7. تظلل الآية عند حدث التشغيل الفعلي `playing` فقط. تتوقف العلامة عند الإيقاف المؤقت أو الخطأ أو الانتظار، وتنتقل تلقائيًا بين الصفحات عند تفعيل المتابعة.
+8. مظهر القراءة: فاتح، داكن، أو حسب الجهاز. يحفظ الخيار محليًا ويقتصر على نافذة القرآن وإعداداتها.
+9. إعدادات حجم الخط وتذكر آخر صفحة ومتابعة الآية موجودة داخل إعدادات القراءة، ويمكن الوصول إليها أيضًا من إعدادات الساعة الموجودة.
+10. زر الإغلاق الموجود يغلق النافذة ويوقف التلاوة ويلغي أي تشغيل متأخر؛ لا يسجل إتمام عبادة أو ختمة. الانتقال من نافذة القراءة إلى إعداداتها يوقف الصوت أيضًا.
 
 يحمّل الملف الصغير الخاص بواجهة القارئ عند فتح مدخله، وبيانات القرآن عند فتح القراءة لأول مرة.
 بعد تحميل البيانات يستخدمها القارئ من ذاكرة الصفحة دون اتصال إضافي. لا تضمن هذه المرحلة فتح التطبيق من جديد دون إنترنت؛ ذلك يحتاج تخزينًا دائمًا وآلية عمل دون اتصال لاحقًا.
 إعدادات القراءة وآخر صفحة فقط تحفظ محليًا على الجهاز؛ لا حساب ولا إرسال لبحث المستخدم إلى خدمة خارجية.
 
-النسخة الحالية قراءة نصية؛ لا صور مصحف أو صوت أو تفسير أو خطة ختمة بعد، ولا ذكاء اصطناعي في القرآن.
+النسخة الحالية قراءة نصية وتلاوة آيةً آية؛ لا صور مصحف أو تفسير أو خطة ختمة بعد، ولا ذكاء اصطناعي في القرآن.
 هذه الأقسام يمكن ربطها لاحقًا بملفات مستقلة. لا تتضمن الإضافة نقل كود القبلة والمحاكاة الموجود مسبقًا داخل الاندكس.
 
 ## عقد الربط للصيانة
@@ -60,17 +67,32 @@ node maintenance/test_quran_reader.cjs
 
 الاختبار يحتاج Node.js وPlaywright وChromium. يستخدم مدير النافذة ومدخل الساعة الفعليين مع بيانات اختبار للأجزاء غير المرفقة من الساعة؛ ليس اختبارًا كاملًا للمواقيت والتنبيهات أو للمساحة المنشورة.
 
+## مصدر التلاوات والتحقق
+
+- المصدر المعتمد للتشغيل: https://everyayah.com/ وفهرس القرّاء الرسمي https://everyayah.com/data/recitations.js
+- تمت مراجعة MP3Quran أيضًا: https://www.mp3quran.net/ar/api وhttps://www.mp3quran.net/eng/timing-api . لم يُضف كمزود ثانٍ في هذه المرحلة؛ الاختيار هو المقاطع المنفصلة لكل آية من EveryAyah.
+- نمط الرابط: `https://everyayah.com/data/{folder}/{surah3}{ayah3}.mp3`، مثل `002255.mp3` للبقرة 255. مجلدات القرّاء مأخوذة من فهرس المصدر، لا من تخمين أسماء روابط.
+- في 2026-09-28 طوبقت أسماء الملفات في فهارس `Alafasy_128kbps` و`Husary_128kbps` و`Minshawy_Murattal_128kbps` مع بياناتنا: وُجدت أسماء المقاطع لكل الآيات الـ6236 عند كل قارئ. هذا تحقق فهرسة، وليس استماعًا وتدقيقًا لكل تسجيل.
+- استجابت عينات العفاسي 1:1 والحصري 114:6 والمنشاوي 2:255 بحالة HTTP 200 وبنوع `audio/mpeg`، ويدعم الخادم الطلبات الجزئية. نُزّلت عينة العفاسي للفحص التقني وتعرّف عليها ffprobe كملف MP3 مدته نحو 6.09 ثوان.
+- نص القرآن يظل من AL-Khatma كما هو. لم يتم استبدال `quran_core_registry.json` أو تغيير نصوصه بهذه الإضافة.
+- التسجيلات تُبث من المصدر عند طلب المستخدم، ولا تدخل ضمن ترخيص بيانات AL-Khatma ولا ترفع ضمن ملفات المساحة. لا يوجد تنزيل كامل للتلاوات أو تخزين دائم دون إنترنت في هذه المرحلة.
+- قد يفصل بين المقاطع توقف قصير. إذا منع المتصفح استكمال التشغيل التلقائي يظهر طلب ضغط «تشغيل»؛ لا يُدّعى دعم تشغيل مضمون بعد إغلاق الصفحة أو التطبيق.
+- تأخذ كل آية التسجيل المقابل لرقمها؛ لا نضيف بسملة صوتية مصطنعة أو نفترض وجود توقيتات كلمات داخل التسجيل.
+
 ## نتيجة التحقق لهذه النسخة
 
 - نجح فحص مطابقة النصوص والحقول لكل الآيات الـ6236 مع الملف الأصلي، وترتيب 114 سورة و604 صفحات و30 جزءًا.
-- نجح التحقق من بقاء محتوى الاندكس الأصلي كما هو بعد استثناء روابط القارئ وإصدار رابط `registry_app.js`.
+- ظل تعديل الاندكس مقتصرًا على روابط ملفات القرآن وأرقام إصدارات التحميل؛ كود الصوت خارج الاندكس. تعديل `registry_app.js` الإضافي يتيح التنقل بلوحة المفاتيح بين الآيات وإجراءات الصوت ويتجاوز الحقول المعطلة أو المطوية.
 - نجح اختبار السلوك بواسطة jsdom: فتح القارئ من الساعة، السورة والجزء والصفحة، البحث العربي، صفحات نتائج البحث، الإعدادات، التخزين المحلي، الإغلاق، إعادة استخدام البيانات، فتح آية من حدث، إعادة المحاولة بعد خطأ بيانات أو إعدادات، وإلغاء عرض نتيجة تحميل متأخر بعد الإغلاق.
 - لم يعمل اختبار Playwright البصري لعدم توفر Chromium وتعذر تنزيله في بيئة التنفيذ. لم تُراجع هيئة العرض على متصفح هاتف فعلي ولم تختبر المساحة المنشورة.
+- نجح اختبار الصوت بمحاكاة أحداث الوسائط: التظليل عند التشغيل فقط، السابق والتالي وعبر الصفحات والسور، التكرار المحدود والمستمر، السرعة وشريط التقدم، تغيير القارئ، إغلاق وإيقاف تشغيل متأخر، خطأ المصدر وإعادة المحاولة، منع التشغيل التلقائي، ونهاية القرآن.
+- نجح فحص الوضع الداكن وحفظه محليًا، نسخ الآية ومرجعها، وبقاء ميزات القراءة السابقة. لا تمثل محاكاة أحداث الوسائط تجربة استماع فعلية داخل متصفح.
 
 لاختبار السلوك دون Chromium، مع إتاحة حزمة `jsdom` لـNode:
 
 ```bash
 node maintenance/test_quran_dom.cjs
+node maintenance/test_quran_audio.cjs
 ```
 
 بدائل TXT تطابق الملفات الأصلية بايتًا ببايت؛ هي بدائل للتنزيل فقط ولا يحتاج التطبيق النسختين معًا.

index.html

@@ -4,7 +4,7 @@
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
 <title></title>
-<link rel="stylesheet" href="quran_reader.css?v=20260928-quran1">
+<link rel="stylesheet" href="quran_reader.css?v=20260928-audio2">
 <style>
 *{box-sizing:border-box}
 html,body{margin:0;min-height:100%;font-family:system-ui,-apple-system,"Noto Sans Arabic",sans-serif}
@@ -225,8 +225,9 @@ body{padding-bottom:190px}
 <script src="personal_reminder_engine.js?v=20260927-markers2"></script>
 <script src="hijri_calendar_engine.js?v=20260926-worship1"></script>
 <script src="worship_event_engine.js?v=20260926-worship1"></script>
-<script src="quran_reader.js?v=20260928-quran1"></script>
-<script src="registry_app.js?v=20260928-quran1"></script>
+<script src="quran_audio.js?v=20260928-audio2"></script>
+<script src="quran_reader.js?v=20260928-audio2"></script>
+<script src="registry_app.js?v=20260928-audio2"></script>
 <script>
 (function () {
   'use strict';

quran_audio.js

@@ -0,0 +1,200 @@
+(function () {
+  'use strict';
+  const base = new URL('.', document.currentScript.src);
+  let configPromise;
+  const element = (tag, text, className) => {
+    const node = document.createElement(tag);
+    if (text != null) node.textContent = text;
+    if (className) node.className = className;
+    return node;
+  };
+  const button = (label, action) => {
+    const node = element('button', label); node.type = 'button'; node.addEventListener('click', action); return node;
+  };
+  const interpolate = (text, values) => text.replace(/\{(\w+)\}/g, (_, key) => String(values[key] ?? ''));
+  async function configuration() {
+    if (!configPromise) configPromise = (async () => {
+      const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 15000);
+      try {
+        const response = await fetch(new URL('quran_audio_registry.json', base), {signal:controller.signal,cache:'no-store'});
+        if (!response.ok) throw Error('quran_audio_registry.json HTTP ' + response.status);
+        const c = await response.json();
+        if (c.schema_version !== 1 || !Array.isArray(c.reciters) || !c.reciters.length || !c.ui || !c.defaults ||
+          !Array.isArray(c.rates) || !c.repeat_options?.length || !c.limits?.loading_timeout_ms) throw Error('Invalid audio registry');
+        for (const r of c.reciters) if (!r.id || !r.name || !/^[A-Za-z0-9_.-]+$/.test(r.folder)) throw Error('Invalid reciter');
+        if (!c.reciters.some(r => r.id === c.defaults.reciter)) throw Error('Missing default reciter');
+        for (const key of ['title','options','reciter','rate','repeat','advance','play','pause','resume','stop','previous','next','seek',
+          'current','idle','loading','playing','paused','stopped','ended','error','blocked','storage_error','source']) {
+          if (typeof c.ui[key] !== 'string') throw Error('Missing audio UI: ' + key);
+        }
+        return c;
+      } finally {clearTimeout(timer);}
+    })().catch(error => {configPromise = null; throw error;});
+    return configPromise;
+  }
+  function createPlayer(c, verses, notify) {
+    const byId = new Map(verses.map((v, index) => [v.id, index]));
+    let saved;
+    try {saved = JSON.parse(localStorage.getItem(c.storage_key));} catch { /* Preferences are optional. */ }
+    const settings = {
+      reciter: c.reciters.some(r => r.id === saved?.reciter) ? saved.reciter : c.defaults.reciter,
+      rate: c.rates.includes(saved?.rate) ? saved.rate : c.defaults.rate,
+      repeat: c.repeat_options.some(r => r.value === saved?.repeat) ? saved.repeat : c.defaults.repeat,
+      advance: typeof saved?.advance === 'boolean' ? saved.advance : c.defaults.advance
+    };
+    let index = 0, media = null, token = 0, playRequest = 0, disposed = false, wantsPlay = false, repetitions = settings.repeat;
+    let phase = 'idle', currentTime = 0, duration = 0, loadTimer, removeEvents = () => {};
+    const snapshot = () => ({verse:verses[index], phase, currentTime, duration, settings:{...settings}});
+    const emit = () => {if (!disposed) notify(snapshot());};
+    const clearTimer = () => {clearTimeout(loadTimer);loadTimer = null;};
+    function detach() {
+      clearTimer(); token++; playRequest++; wantsPlay = false;
+      removeEvents(); removeEvents = () => {};
+      if (media) {media.pause(); media.removeAttribute('src'); media.load(); media = null;}
+    }
+    function fail(kind = 'error') {
+      clearTimer(); wantsPlay = false; playRequest++;
+      if (media) media.pause(); phase = kind; emit();
+    }
+    function watchLoading() {
+      clearTimer();
+      loadTimer = setTimeout(() => {if (wantsPlay) fail();}, c.limits.loading_timeout_ms);
+    }
+    function urlFor(verse) {
+      const reciter = c.reciters.find(r => r.id === settings.reciter);
+      const raw = interpolate(c.source.url_pattern, {folder:reciter.folder, surah3:String(verse.surah).padStart(3,'0'), ayah3:String(verse.ayah).padStart(3,'0')});
+      const url = new URL(raw);
+      if (url.protocol !== 'https:' || url.hostname !== new URL(c.source.url).hostname) throw Error('Invalid audio URL');
+      return url.href;
+    }
+    async function startMedia() {
+      if (disposed) return;
+      const activeMedia = media, request = ++playRequest;
+      wantsPlay = true; phase = 'loading'; watchLoading(); emit();
+      try { await activeMedia.play(); }
+      catch (error) {
+        if (!disposed && activeMedia === media && request === playRequest && wantsPlay) fail(error.name === 'NotAllowedError' ? 'blocked' : 'error');
+      }
+    }
+    function playAt(id, resetRepeat = true) {
+      if (disposed || !byId.has(id)) return;
+      detach(); index = byId.get(id); currentTime = 0; duration = 0;
+      if (resetRepeat) repetitions = settings.repeat;
+      const activeMedia = new Audio(); media = activeMedia;
+      activeMedia.preload = 'none'; activeMedia.playbackRate = settings.rate;
+      activeMedia.setAttribute('playsinline', '');
+      const generation = token;
+      const listeners = [];
+      const on = (name, fn) => {
+        const handler = () => {if (!disposed && generation === token && activeMedia === media) fn();};
+        activeMedia.addEventListener(name, handler); listeners.push([name,handler]);
+      };
+      removeEvents = () => listeners.forEach(([name,handler]) => activeMedia.removeEventListener(name,handler));
+      on('playing', () => {
+        if (!wantsPlay) {activeMedia.pause(); return;}
+        clearTimer(); phase = 'playing'; emit();
+      });
+      on('waiting', () => {if (wantsPlay) {phase = 'loading'; watchLoading(); emit();}});
+      on('stalled', () => {if (wantsPlay) {phase = 'loading'; watchLoading(); emit();}});
+      on('pause', () => {if (phase === 'playing') {wantsPlay = false; clearTimer(); phase = 'paused'; emit();}});
+      on('loadedmetadata', () => {duration = Number.isFinite(activeMedia.duration) ? activeMedia.duration : 0; emit();});
+      on('durationchange', () => {duration = Number.isFinite(activeMedia.duration) ? activeMedia.duration : 0; emit();});
+      on('timeupdate', () => {currentTime = activeMedia.currentTime || 0; emit();});
+      on('error', () => fail());
+      on('ended', () => {
+        if (!wantsPlay) return;
+        clearTimer();
+        if (repetitions === 0 || repetitions > 1) {
+          if (repetitions > 1) repetitions--;
+          playAt(verses[index].id, false);
+        } else if (settings.advance && index < verses.length - 1) playAt(verses[index + 1].id);
+        else {wantsPlay = false; phase = 'ended'; emit();}
+      });
+      try {activeMedia.src = urlFor(verses[index]); startMedia();} catch {fail();}
+    }
+    function select(id) {
+      if (disposed || !byId.has(id) || verses[index].id === id) return;
+      detach(); index = byId.get(id); phase = 'idle'; currentTime = 0; duration = 0; emit();
+    }
+    function pause() {
+      if (!media || disposed) return;
+      wantsPlay = false; playRequest++; clearTimer(); media.pause(); phase = 'paused'; emit();
+    }
+    function stop() {detach(); phase = 'stopped'; currentTime = 0; duration = 0; emit();}
+    function toggle() {
+      if (phase === 'playing' || phase === 'loading') pause();
+      else if (media && ['paused','blocked'].includes(phase)) startMedia();
+      else playAt(verses[index].id);
+    }
+    function configure(patch) {
+      const oldReciter = settings.reciter, running = wantsPlay;
+      if (c.reciters.some(r => r.id === patch.reciter)) settings.reciter = patch.reciter;
+      if (c.rates.includes(patch.rate)) settings.rate = patch.rate;
+      if (c.repeat_options.some(r => r.value === patch.repeat)) {settings.repeat = patch.repeat;repetitions = patch.repeat;}
+      if (typeof patch.advance === 'boolean') settings.advance = patch.advance;
+      if (oldReciter !== settings.reciter) {stop(); if (running) playAt(verses[index].id);}
+      if (media) media.playbackRate = settings.rate;
+      let stored = true;
+      try {localStorage.setItem(c.storage_key, JSON.stringify(settings));} catch {stored = false;}
+      emit(); return stored;
+    }
+    function seek(seconds) {
+      if (media && Number.isFinite(seconds) && duration > 0) {
+        try {media.currentTime = Math.min(duration, Math.max(0, seconds));currentTime = media.currentTime;emit();} catch { /* Metadata may be changing. */ }
+      }
+    }
+    return {playAt, select, pause, stop, toggle, configure, seek, snapshot,
+      previous: () => {if (index > 0) playAt(verses[index - 1].id);},
+      next: () => {if (index < verses.length - 1) playAt(verses[index + 1].id);},
+      dispose: () => {disposed = true;detach();}};
+  }
+  async function mount(host, {verses, surahs, initialId, onState, isActive = () => host.isConnected}) {
+    const c = await configuration();
+    if (!isActive()) return null;
+    const ui = c.ui, wrap = element('section', null, 'quran-audio'); wrap.setAttribute('aria-label',ui.title);
+    const controls = element('div', null, 'quran-audio-options');
+    const select = (label, options, action) => {
+      const box = element('label',label), input = element('select');
+      options.forEach(([value,text]) => {const item = element('option',text);item.value=value;input.append(item);});
+      input.addEventListener('change', () => action(input.value));box.append(input);controls.append(box);return input;
+    };
+    const storageStatus = element('p',null,'quran-meta');storageStatus.setAttribute('role','status');
+    let player;
+    const set = patch => {storageStatus.textContent = player.configure(patch) ? '' : ui.storage_error;};
+    const reciter = select(ui.reciter,c.reciters.map(r=>[r.id,r.name]),value=>set({reciter:value}));
+    const rate = select(ui.rate,c.rates.map(r=>[r,r+'×']),value=>set({rate:Number(value)}));
+    const repeat = select(ui.repeat,c.repeat_options.map(r=>[r.value,r.label]),value=>set({repeat:Number(value)}));
+    const advanceLabel=element('label',ui.advance), advance=element('input');advance.type='checkbox';
+    advance.addEventListener('change',()=>set({advance:advance.checked}));advanceLabel.prepend(advance);
+    const actions=element('div',null,'quran-audio-actions');
+    const previous=button(ui.previous,()=>player.previous()), play=button(ui.play,()=>player.toggle());
+    const stop=button(ui.stop,()=>player.stop()), next=button(ui.next,()=>player.next());actions.append(previous,play,stop,next);
+    const current=element('p',null,'quran-meta'), state=element('p',null,'quran-meta');state.setAttribute('role','status');
+    const seekLabel=element('label',ui.seek), seek=element('input');seek.type='range';seek.min=0;seek.max=0;seek.step=0.1;seek.value=0;seek.disabled=true;
+    seek.addEventListener('change',()=>player.seek(Number(seek.value)));seekLabel.append(seek);
+    const clock=element('output');clock.dir='ltr';
+    const time=s=>Math.floor(s/60)+':'+String(Math.floor(s%60)).padStart(2,'0');
+    const source=element('a',ui.source);source.href=c.source.url;source.target='_blank';source.rel='noopener noreferrer';source.className='quran-meta';
+    let lastStatus='';
+    player=createPlayer(c,verses,s=>{
+      if (!isActive()) return;
+      reciter.value=s.settings.reciter;rate.value=s.settings.rate;repeat.value=s.settings.repeat;advance.checked=s.settings.advance;
+      current.textContent=interpolate(ui.current,{surah:surahs[s.verse.surah-1].name,ayah:s.verse.ayah});
+      if (lastStatus !== s.phase) {state.textContent=ui[s.phase]||ui.idle;lastStatus=s.phase;}
+      play.textContent=['playing','loading'].includes(s.phase)?ui.pause:s.phase==='paused'?ui.resume:ui.play;
+      previous.disabled=s.verse.id===verses[0].id;next.disabled=s.verse.id===verses[verses.length-1].id;
+      seek.max=s.duration;seek.disabled=s.duration<=0;
+      if (document.activeElement!==seek) seek.value=s.currentTime;
+      clock.textContent=time(s.currentTime)+' / '+time(s.duration);
+      onState(s);
+    });
+    const options=element('details'),summary=element('summary',ui.options);
+    options.append(summary,controls,advanceLabel,source);
+    wrap.append(current,actions,seekLabel,clock,state,options,storageStatus);host.replaceChildren(wrap);
+    player.select(initialId);
+    // Initialize controls even when the requested verse is already the first one.
+    player.configure({});
+    return player;
+  }
+  window.MuslimClockQuranAudio=Object.freeze({mount,createPlayer});
+})();

quran_audio_registry.json

@@ -0,0 +1,48 @@
+{
+  "schema_version": 1,
+  "storage_key": "muslim_clock_quran_audio_v1",
+  "source": {
+    "name": "EveryAyah",
+    "url": "https://everyayah.com/",
+    "catalog_url": "https://everyayah.com/data/recitations.js",
+    "url_pattern": "https://everyayah.com/data/{folder}/{surah3}{ayah3}.mp3",
+    "checked_on": "2026-09-28",
+    "delivery": "remote_stream_on_user_play",
+    "note": "Verse filenames use three digits for the surah and three for the ayah. Recordings are linked, not redistributed or licensed as part of AL-Khatma."
+  },
+  "reciters": [
+    {"id": "alafasy", "name": "مشاري راشد العفاسي", "folder": "Alafasy_128kbps"},
+    {"id": "husary", "name": "محمود خليل الحصري", "folder": "Husary_128kbps"},
+    {"id": "minshawy", "name": "محمد صديق المنشاوي", "folder": "Minshawy_Murattal_128kbps"}
+  ],
+  "defaults": {"reciter": "alafasy", "rate": 1, "repeat": 1, "advance": true},
+  "rates": [0.75, 1, 1.25, 1.5],
+  "repeat_options": [{"value":1,"label":"مرة واحدة"},{"value":2,"label":"مرتان"},{"value":3,"label":"3 مرات"},{"value":5,"label":"5 مرات"},{"value":0,"label":"تكرار مستمر"}],
+  "limits": {"request_timeout_ms": 15000, "loading_timeout_ms": 30000},
+  "ui": {
+    "title": "الاستماع",
+    "options": "القارئ وخيارات التلاوة",
+    "reciter": "القارئ",
+    "rate": "سرعة التلاوة",
+    "repeat": "تكرار كل آية",
+    "advance": "متابعة الآيات والسور تلقائيًا",
+    "play": "تشغيل",
+    "pause": "إيقاف مؤقت",
+    "resume": "استكمال",
+    "stop": "إيقاف التلاوة",
+    "previous": "الآية السابقة",
+    "next": "الآية التالية",
+    "seek": "موضع التلاوة في الآية",
+    "current": "{surah} · الآية {ayah}",
+    "idle": "اختر آية للاستماع",
+    "loading": "جارٍ تحميل التلاوة…",
+    "playing": "تُتلى الآن",
+    "paused": "التلاوة متوقفة مؤقتًا",
+    "stopped": "توقفت التلاوة",
+    "ended": "انتهت التلاوة",
+    "error": "تعذّر تشغيل المقطع. تحقق من الإنترنت أو اختر قارئًا آخر ثم اضغط تشغيل.",
+    "blocked": "اضغط تشغيل لاستكمال التلاوة؛ المتصفح يحتاج ضغطة منك.",
+    "storage_error": "تعذّر حفظ تفضيلات الصوت على هذا الجهاز.",
+    "source": "مصدر التلاوة: EveryAyah"
+  }
+}

quran_reader.css

@@ -21,6 +21,30 @@
 #adaptivePopupBody .quran-result-text{display:block;font-family:"Noto Naskh Arabic","Amiri",serif;font-size:var(--quran-font-size,26px);line-height:2}
 #adaptivePopupBody .quran-settings input[type="range"]{width:100%;padding:0;min-height:44px}
 #adaptivePopupBody .quran-settings input[type="checkbox"]{width:auto}
+#adaptivePopupCard[data-quran-theme]{background:var(--quran-bg);color:var(--quran-fg);border-color:var(--quran-border);color-scheme:light}
+#adaptivePopupCard[data-quran-theme="dark"]{color-scheme:dark}
+#adaptivePopupCard[data-quran-theme] button,
+#adaptivePopupCard[data-quran-theme] input,
+#adaptivePopupCard[data-quran-theme] select,
+#adaptivePopupCard[data-quran-theme] textarea{background:var(--quran-surface);color:var(--quran-fg);border:1px solid var(--quran-border)}
+#adaptivePopupCard[data-quran-theme] a{color:var(--quran-fg)}
+#adaptivePopupBody .quran-verse{cursor:pointer;border-radius:3px;box-decoration-break:clone;-webkit-box-decoration-break:clone}
+#adaptivePopupBody .quran-verse.quran-playing{background:var(--quran-highlight);color:var(--quran-highlight_fg);outline:2px solid var(--quran-border);outline-offset:2px}
+#adaptivePopupBody .quran-ayah-actions{border-block:1px solid var(--quran-border);padding:8px 0;margin:8px 0}
+#adaptivePopupBody .quran-ayah-actions[hidden]{display:none}
+#adaptivePopupBody .quran-ayah-actions h3{font-size:1rem;margin:4px 0}
+#adaptivePopupBody .quran-audio{border-block:1px solid var(--quran-border);padding:10px 0;margin:12px 0}
+#adaptivePopupBody .quran-audio-options{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px;align-items:end}
+#adaptivePopupBody .quran-audio-options label{margin:0;min-width:0}
+#adaptivePopupBody .quran-audio-options label:first-child{grid-column:1/-1}
+#adaptivePopupBody .quran-audio-options select{min-width:0;max-width:100%}
+#adaptivePopupBody .quran-audio-actions{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:6px}
+#adaptivePopupBody .quran-audio-actions button{min-width:0;margin:0;text-align:center;padding:8px}
+#adaptivePopupBody .quran-audio input[type="range"]{width:100%;min-width:0;padding:0;min-height:44px;accent-color:var(--quran-fg)}
+#adaptivePopupBody .quran-audio input[type="checkbox"]{width:auto}
+#adaptivePopupBody .quran-audio output{display:block;text-align:center;font-variant-numeric:tabular-nums}
+#adaptivePopupBody .quran-audio p:empty{display:none}
+#adaptivePopupBody .quran-audio summary{cursor:pointer;min-height:44px;padding:8px 0}
 #adaptivePopupBody .quran-reader :focus-visible,
 #adaptivePopupBody .quran-settings :focus-visible{outline:2px solid currentColor;outline-offset:2px}
 @media(max-width:400px){

quran_reader.js

@@ -2,7 +2,7 @@
   'use strict';
   const base = new URL('.', document.currentScript.src);
   const configFile = 'quran_reader_registry.json';
-  let configPromise, corePromise, preferences, epoch = 0;
+  let configPromise, corePromise, preferences, epoch = 0, cleanup = () => {};
   const node = (tag, text, className) => {
     const element = document.createElement(tag);
     if (text != null) element.textContent = text;
@@ -26,7 +26,7 @@
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeout);
     try {
-      const response = await fetch(url, {signal: controller.signal});
+      const response = await fetch(url, {signal: controller.signal, cache:file===configFile?'no-store':'default'});
       if (!response.ok) throw Error(file + ' HTTP ' + response.status);
       return await response.json();
     } finally { clearTimeout(timer); }
@@ -36,7 +36,8 @@
       if (value.schema_version !== 1 || !value.ui || !value.core_file || !value.defaults || !value.limits) throw Error('Invalid reader registry');
       for (const key of ['title','open','settings','loading','load_error','retry','surah','ayah','page','juz','go','previous','next',
         'search','search_submit','search_empty','no_results','results','more','reader','page_status','invalid_page','font_size',
-        'remember_page','save','saved','storage_error','back','source']) {
+        'remember_page','save','saved','storage_error','back','source','theme','theme_auto','theme_light','theme_dark',
+        'follow_audio','verse_actions','listen','copy','copied','copy_failed','close_actions','audio_loading','audio_unavailable','search_surah']) {
         if (typeof value.ui[key] !== 'string') throw Error('Missing UI: ' + key);
       }
       if (!Number.isInteger(value.limits.search_batch) || value.limits.search_batch < 1) throw Error('Invalid search limit');
@@ -79,7 +80,9 @@
     preferences = {
       font_size: Number.isFinite(saved?.font_size) ? Math.max(c.limits.font_min, Math.min(c.limits.font_max, saved.font_size)) : c.defaults.font_size,
       remember_page: typeof saved?.remember_page === 'boolean' ? saved.remember_page : c.defaults.remember_page,
-      page: Number.isInteger(saved?.page) && saved.page >= 1 && saved.page <= 604 ? saved.page : 1
+      page: Number.isInteger(saved?.page) && saved.page >= 1 && saved.page <= 604 ? saved.page : 1,
+      theme: ['auto','light','dark'].includes(saved?.theme) ? saved.theme : c.defaults.theme,
+      follow_audio: typeof saved?.follow_audio === 'boolean' ? saved.follow_audio : c.defaults.follow_audio
     };
     return preferences;
   }
@@ -94,6 +97,17 @@
     });
     document.getElementById('adaptivePopupCard').dataset.size = 'long';
   }
+  function applyTheme(c, p) {
+    const card = document.getElementById('adaptivePopupCard');
+    const mode = p.theme === 'auto' ? (window.matchMedia?.('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : p.theme;
+    card.dataset.quranTheme = mode;
+    for (const [key,value] of Object.entries(c.themes[mode])) card.style.setProperty('--quran-'+key,value);
+  }
+  function themeField(c, p, onChange) {
+    const label = node('label',c.ui.theme), select = node('select');
+    for (const key of ['auto','light','dark']) {const option=node('option',c.ui['theme_'+key]);option.value=key;select.append(option);}
+    select.value=p.theme;select.addEventListener('change',()=>onChange(select.value));label.append(select);return label;
+  }
   async function mount(parent, back, settingsOnly) {
     const entry = button('…', () => {});
     entry.disabled = true;
@@ -151,6 +165,10 @@
     }
     root.replaceChildren();
     root.style.setProperty('--quran-font-size', p.font_size + 'px');
+    applyTheme(c,p);
+    let player = null, mounted = true, audioState = null, lastFollowed = null, actionVerse = null, actionOrigin = null;
+    let audioAttempt = 0;
+    cleanup = () => {mounted=false;audioAttempt++;player?.dispose();};
     const toolbar = node('div', null, 'quran-toolbar');
     const field = (label, input) => { const wrap = node('label', label); wrap.append(input); toolbar.append(wrap); return input; };
     const select = (items, label) => {
@@ -159,6 +177,13 @@
       return field(label, input);
     };
     const surahSelect = select(source.surahs.map(s => [s.id, s.id + '. ' + s.name]), ui.surah);
+    const surahSearch = node('input');surahSearch.type='search';surahSearch.placeholder=ui.search_surah;surahSearch.setAttribute('aria-label',ui.search_surah);
+    const surahSearchLabel=node('label',ui.search_surah);surahSearchLabel.append(surahSearch);
+    toolbar.insertBefore(surahSearchLabel,surahSelect.parentElement);
+    surahSearch.addEventListener('input',()=>{
+      const term=normalize(surahSearch.value);
+      for(const option of surahSelect.options) option.hidden=Boolean(term)&&!normalize(option.textContent).includes(term);
+    });
     const juzSelect = select(Array.from({length: source.counts.juz}, (_, i) => [i + 1, i + 1]), ui.juz);
     const pageForm = node('form');
     const pageLabel = node('label', ui.page);
@@ -167,22 +192,76 @@
     pageLabel.append(pageInput); pageForm.append(pageLabel);
     const go = node('button', ui.go); go.type = 'submit'; pageForm.append(go); toolbar.append(pageForm);
     toolbar.append(button(ui.settings, () => openSettings(() => open({...options, page, surah: undefined, ayah: undefined}))));
+    toolbar.append(themeField(c,p,value=>{p.theme=value;applyTheme(c,p);if(!persist(c))status.textContent=ui.storage_error;}));
     const searchForm = node('form', null, 'quran-search'); searchForm.setAttribute('role', 'search');
     const query = node('input'); query.type = 'search'; query.setAttribute('aria-label', ui.search); query.placeholder = ui.search;
     const submit = node('button', ui.search_submit); submit.type = 'submit'; searchForm.append(query, submit);
     const status = node('p', null, 'quran-meta'); status.setAttribute('role', 'status');
     const content = node('div');
+    const audioHost=node('div');
+    const actions=node('section',null,'quran-ayah-actions');actions.hidden=true;actions.setAttribute('aria-label',ui.verse_actions);
+    const actionTitle=node('h3'), actionStatus=node('p');actionStatus.setAttribute('role','status');
+    const listen=button(ui.listen,()=>{if(player&&actionVerse){player.playAt(actionVerse.id);actions.hidden=true;actionOrigin?.focus();}});
+    listen.disabled=true;
+    const copy=button(ui.copy,async()=>{
+      if(!actionVerse)return;
+      const text=actionVerse.text+'\n['+source.surahs[actionVerse.surah-1].name+': '+actionVerse.ayah+']';
+      try{await navigator.clipboard.writeText(text);actionStatus.textContent=ui.copied;}
+      catch{
+        const input=node('textarea',text);input.readOnly=true;input.setAttribute('aria-label',ui.copy);
+        actionStatus.replaceChildren(node('span',ui.copy_failed),input);input.focus();input.select();
+      }
+    });
+    actions.append(actionTitle,listen,copy,button(ui.close_actions,()=>{actions.hidden=true;actionOrigin?.focus();}),actionStatus);
+    function selectVerse(verse, origin) {
+      actionVerse=verse;actionOrigin=origin;
+      actionTitle.textContent=source.surahs[verse.surah-1].name+' · '+ui.ayah+' '+verse.ayah;
+      actionStatus.replaceChildren();actions.hidden=false;(listen.disabled?copy:listen).focus();
+    }
     const nav = node('div', null, 'quran-nav');
     const previous = button(ui.previous, () => showPage(page - 1));
     const next = button(ui.next, () => showPage(page + 1)); nav.append(previous, next);
     const attribution = node('a', ui.source); attribution.href = new URL(c.source_file, base).href;
     attribution.target = '_blank'; attribution.rel = 'noopener'; attribution.className = 'quran-meta';
-    root.append(toolbar, searchForm, status, content, nav, attribution);
-    function showPage(value, selectedVerse) {
+    root.append(toolbar, audioHost, searchForm, status, actions, content, nav, attribution);
+    function paintPlaying() {
+      for(const verse of content.querySelectorAll('.quran-verse')) {
+        const playing=audioState?.phase==='playing'&&verse.id==='quran-verse-'+audioState.verse.id;
+        verse.classList.toggle('quran-playing',playing);
+        if(playing)verse.setAttribute('aria-current','true');else verse.removeAttribute('aria-current');
+      }
+    }
+    function audioChanged(state) {
+      if(!mounted)return;
+      audioState=state;
+      if(state.phase==='playing'&&state.verse.id!==lastFollowed&&p.follow_audio) {
+        lastFollowed=state.verse.id;
+        if(page!==state.verse.page||!content.querySelector('.quran-page-text'))showPage(state.verse.page,null,true);
+        document.getElementById('quran-verse-'+state.verse.id)?.scrollIntoView({block:'nearest'});
+      }
+      paintPlaying();
+    }
+    async function mountAudio() {
+      const attempt=++audioAttempt;
+      audioHost.replaceChildren(node('p',ui.audio_loading,'quran-meta'));
+      try {
+        if(!window.MuslimClockQuranAudio)throw Error('quran_audio.js');
+        const nextPlayer=await window.MuslimClockQuranAudio.mount(audioHost,{
+          verses:source.verses,surahs:source.surahs,initialId:focusVerse?.id||source.pages[page][0].id,
+          isActive:()=>mounted&&attempt===audioAttempt&&root.isConnected,onState:audioChanged
+        });
+        if(!mounted||attempt!==audioAttempt){nextPlayer?.dispose();return;}
+        player=nextPlayer;listen.disabled=!player;
+      } catch(error) {
+        if(!mounted||attempt!==audioAttempt)return;
+        audioHost.replaceChildren(node('p',ui.audio_unavailable,'quran-meta'),button(ui.retry,mountAudio));
+      }
+    }
+    function showPage(value, selectedVerse, fromAudio=false) {
       if (!Number.isInteger(value) || !source.pages[value]?.length) { status.textContent = format(ui.invalid_page, {total:source.counts.pages}); return; }
       page = value;
       const verses = source.pages[page];
-      content.replaceChildren(); nav.hidden = false;
+      content.replaceChildren(); nav.hidden = false;actions.hidden=true;
       pageInput.value = page; surahSelect.value = selectedVerse?.surah || verses[0].surah; juzSelect.value = selectedVerse?.juz || verses[0].juz;
       const juz = [...new Set(verses.map(v => v.juz))].join('، ');
       status.textContent = format(ui.page_status, {page, total: source.counts.pages, juz});
@@ -195,7 +274,10 @@
           paragraph = node('p', null, 'quran-page-text'); content.append(paragraph); lastSurah = verse.surah;
         }
         const span = node('span', verse.text, 'quran-verse');
-        span.id = 'quran-verse-' + verse.id; span.tabIndex = -1;
+        span.id = 'quran-verse-' + verse.id; span.tabIndex = 0;span.setAttribute('role','button');
+        span.setAttribute('aria-label',verse.text+' · '+ui.ayah+' '+verse.ayah+' · '+ui.verse_actions);
+        span.addEventListener('click',()=>selectVerse(verse,span));
+        span.addEventListener('keydown',event=>{if(event.key==='Enter'||event.key===' '){event.preventDefault();selectVerse(verse,span);}});
         const number = node('span', ' (' + verse.ayah + ') ', 'quran-verse-number');
         number.setAttribute('aria-label', ui.ayah + ' ' + verse.ayah);
         span.append(number); paragraph.append(span, document.createTextNode(' '));
@@ -204,7 +286,8 @@
         p.page = page;
         if (!persist(c)) status.textContent += ' ' + ui.storage_error;
       }
-      document.getElementById('adaptivePopupBody').scrollTop = 0;
+      if(!fromAudio){document.getElementById('adaptivePopupBody').scrollTop = 0;player?.select(selectedVerse?.id||verses[0].id);}
+      paintPlaying();
       if (selectedVerse) {
         const target = document.getElementById('quran-verse-' + selectedVerse.id);
         target?.focus({preventScroll: true}); target?.scrollIntoView({block:'center'});
@@ -222,6 +305,7 @@
       const text = normalize(query.value);
       if (!text) { status.textContent = ui.search_empty; query.focus(); return; }
       const matches = source.verses.filter((_, i) => source.searchIndex[i].includes(text));
+      player?.pause();actions.hidden=true;
       content.replaceChildren(); nav.hidden = true;
       status.textContent = matches.length ? format(ui.results, {count: matches.length}) : ui.no_results;
       content.append(button(ui.reader, () => showPage(page)));
@@ -241,6 +325,7 @@
       appendResults();
     });
     showPage(page, focusVerse);
+    mountAudio();
   }
   async function openSettings(back) {
     const request = ++epoch;
@@ -255,14 +340,22 @@
     const rememberLabel = node('label', ui.remember_page), remember = node('input');
     remember.type = 'checkbox'; remember.checked = p.remember_page; rememberLabel.prepend(remember);
     const status = node('p'); status.setAttribute('role', 'status');
-    root.append(label, rememberLabel, button(ui.save, () => {
+    const theme=themeField(c,p,value=>{p.theme=value;applyTheme(c,p);});
+    const followLabel=node('label',ui.follow_audio),follow=node('input');follow.type='checkbox';follow.checked=p.follow_audio;followLabel.prepend(follow);
+    root.append(label, rememberLabel, theme, followLabel, button(ui.save, () => {
       p.font_size = Number(font.value); p.remember_page = remember.checked;
+      p.follow_audio=follow.checked;
       if (!p.remember_page) p.page = 1;
       status.textContent = persist(c) ? ui.saved : ui.storage_error;
     }), status);
     panel(ui.settings, root, back, ui);
+    applyTheme(c,p);
   }
-  window.addEventListener('muslim-clock-popup-leave', () => { epoch++; });
+  window.addEventListener('muslim-clock-popup-leave', () => {
+    epoch++;cleanup();cleanup=()=>{};
+    const card=document.getElementById('adaptivePopupCard');
+    if(card){delete card.dataset.quranTheme;for(const key of ['bg','fg','surface','border','highlight','highlight_fg'])card.style.removeProperty('--quran-'+key);}
+  });
   window.addEventListener('muslim-clock-quran-open', event => open(event.detail || {}));
   window.MuslimClockQuran = Object.freeze({open, openSettings,
     mountEntry: (parent, back) => mount(parent, back, false),

quran_reader_registry.json

@@ -3,7 +3,11 @@
   "core_file": "quran_core_registry.json",
   "source_file": "al_khatma_source_attribution.md",
   "storage_key": "muslim_clock_quran_reader_v1",
-  "defaults": {"font_size": 26, "remember_page": true},
+  "defaults": {"font_size": 26, "remember_page": true, "theme": "auto", "follow_audio": true},
+  "themes": {
+    "light": {"bg":"#ffffff","fg":"#19241d","surface":"#f1f5f2","border":"#7b8980","highlight":"#c5e9d0","highlight_fg":"#102b1a"},
+    "dark": {"bg":"#171b18","fg":"#f0f5f1","surface":"#252c27","border":"#87978c","highlight":"#365a40","highlight_fg":"#ffffff"}
+  },
   "limits": {"font_min": 20, "font_max": 40, "search_batch": 40, "request_timeout_ms": 30000},
   "ui": {
     "title": "القرآن الكريم",
@@ -34,6 +38,20 @@
     "saved": "حُفظت إعدادات القراءة.",
     "storage_error": "تعذّر الحفظ على هذا الجهاز. ستبقى الإعدادات لهذه الجلسة فقط.",
     "back": "رجوع",
-    "source": "مصدر النص والترخيص"
+    "source": "مصدر النص والترخيص",
+    "theme": "مظهر القراءة",
+    "theme_auto": "حسب الجهاز",
+    "theme_light": "فاتح",
+    "theme_dark": "داكن",
+    "follow_audio": "متابعة الآية المتلوة والتنقّل معها",
+    "verse_actions": "إجراءات الآية",
+    "listen": "استماع من هذه الآية",
+    "copy": "نسخ الآية",
+    "copied": "نُسخت الآية مع مرجعها.",
+    "copy_failed": "تعذّر النسخ التلقائي؛ يمكنك تحديد النص ونسخه.",
+    "close_actions": "إغلاق إجراءات الآية",
+    "audio_loading": "جارٍ تجهيز مشغل التلاوة…",
+    "audio_unavailable": "تعذّر تجهيز الصوت. القراءة متاحة؛ أعد محاولة تحميل المشغّل.",
+    "search_surah": "بحث عن سورة"
   }
 }

registry_app.js

@@ -800,7 +800,7 @@ const RegistryApp = (() => {
    if($('adaptivePopup').hidden)return;
    if(e.key==='Escape'){e.preventDefault();close();}
    if(e.key==='Tab'){
-    const nodes=[...$('adaptivePopup').querySelectorAll('button:not([hidden]),a[href],input,select,textarea')].filter(e=>!e.closest('[hidden]')),first=nodes[0],last=nodes[nodes.length-1];
+    const nodes=[...$('adaptivePopup').querySelectorAll('button,a[href],input,select,textarea,summary,[tabindex="0"]')].filter(e=>!e.disabled&&!e.closest('[hidden]')&&e.tabIndex>=0&&(!e.closest('details:not([open])')||e.tagName==='SUMMARY')),first=nodes[0],last=nodes[nodes.length-1];
     if(e.shiftKey&&document.activeElement===first){e.preventDefault();last.focus();}
     else if(!e.shiftKey&&document.activeElement===last){e.preventDefault();first.focus();}
    }