# Sayamuslim - ALQUBBA (aplikasi web PWA)

Aplikasi web di `http://localhost/sayamuslim/` untuk **layar HP portrait** dan bisa
**dipasang (install) sebagai PWA** di layar utama HP.

Isinya dirakit dari berkas di dalam `sayamuslim.apk` - aplikasi ALQUBBA milik
Amanah Media: mushaf 30 juz lengkap dengan tulisan Arab, terjemahan, dan
terjemah per kata untuk belajar bahasa Arab.

---

## Bagian 1 - Aplikasi PWA

### Cara membuka

    http://localhost/sayamuslim/

Untuk dipasang di HP, buka lewat **HTTPS** (atau localhost). PWA hanya bisa
dipasang pada alamat aman - lihat bagian "Memasang di HP" di bawah.

### Halaman

| Berkas | Isi |
|---|---|
| `index.html` | beranda aplikasi: kisi 30 juz, kartu **Per Halaman**, daftar menu, tombol **Pasang** |
| `baca.html` | halaman baca mushaf - bisa **per juz** atau **per halaman** |
| `buku.html` | **Buku PDF per halaman** - 30 juz, 784 berkas PDF siap baca/cetak |
| `katalog.html` | katalog 46 berkas HTML hasil uraian APK (halaman lama, tetap disimpan) |

### Dua cara membaca: per juz dan per halaman

| | Per Juz | Per Halaman |
|---|---|---|
| Alamat | `baca.html?juz=30` | `baca.html?hal=582` |
| Isi yang tampil | seluruh juz (300-345 baris) | satu halaman mushaf (15 baris) |
| Pemilih | 30 pilihan juz | **604 pilihan halaman** |
| Sebelumnya / berikutnya | Juz 29 / Juz 30 | Halaman 581 / Halaman 583 |

- Di beranda ada kartu **Per Halaman**: tautan **Lanjutkan halaman terakhir** (mengingat
  bacaan terakhir lewat `localStorage`) dan isian **lompat ke halaman (1-604)**.
- Di halaman baca ada tombol **Juz/Hlm** di kepala untuk berpindah cara tampil tanpa
  kehilangan posisi: dari Juz 30 pindah ke halaman pertama juz itu, dan sebaliknya.
- Nomor juz untuk setiap halaman diambil dari tautan di
  `isi-apk/assets/qubba/halaman.html` (604 halaman, lengkap 1-604), lalu disimpan
  ringkas di `data/halaman.js`.

### Tampilan khusus HP portrait

- Kerangka aplikasi dibatasi lebar maksimal **520 px** dan ditengahkan, jadi di
  layar lebar pun bentuknya tetap seperti aplikasi HP.
- Kepala (header) menempel di atas dengan warna hijau tua; sudah memakai
  `env(safe-area-inset-*)` supaya aman di iPhone berponi.
- Beranda: kisi **5 kolom x 6 baris** berisi 30 juz, plus daftar menu.
- Halaman baca memakai tinggi `100dvh` sehingga pas satu layar tanpa gulir ganda:
  kepala di atas, isi mushaf menggulir sendiri, navigasi di bawah.
- Ada petunjuk terpisah untuk iPhone/iPad (tombol Bagikan - Tambahkan ke Layar
  Utama) karena iOS tidak memunculkan ajakan pasang otomatis.

### Membuat mushaf pas di layar HP

Berkas `juzN.html` dari APK dibuat untuk layar lebar: tabelnya dipatok
`width="1150"` dan teks Arabnya 25pt, sehingga **meluber jauh** kalau dibuka di
HP (halaman aslinya sampai 851 px lebih lebar dari layar 390 px).

Penyelesaiannya: halaman itu dimuat di dalam `<iframe>`, lalu setelah selesai
dimuat, `js/baca.js` menyuntikkan `gaya/mushaf.css` dan **menata ulang setiap
baris mushaf**. Setiap baris aslinya berupa tabel dengan satu sel per kata
(baris pertama tulisan Arab, baris kedua terjemah per kata), jadi tiap sel
diubah menjadi satu **kepingan** berisi kata Arab di atas dan artinya di bawah:

    <div class="baris-ayat" dir="rtl">
      <div class="keping-kata">
        <span class="kata-arab">...</span>
        <span class="kata-glos">...</span>
      </div>
      ...
    </div>

Kepingan disusun dengan `flex-wrap` berarah **RTL** supaya urutan bacaan Arab
benar (kata pertama di kanan) dan sambungan baris berikutnya tetap mengalir dari
kanan ke kiri. Hasilnya di Juz 30: 345 baris mushaf diubah menjadi 4.062 kepingan
kata, dan lebar halaman pas 390 px tanpa meluber.

Berkas asli di `isi-apk/` **tidak diubah sama sekali** - semua penyesuaian
dilakukan saat halaman dibuka.

#### Memisahkan satu halaman dari berkas per juz

Berkas `juzN.html` memuat **banyak halaman** sekaligus: Juz 30 berisi 23 halaman
(582-604), Juz 1 berisi 21 halaman (1-21), seluruhnya 604 halaman. Batas setiap
halaman dikenali dari tabel bingkai atas (`borderatas`) dan bawah
(`borderbawah`), dan nomor halamannya dibaca dari penanda di dalam baris mushaf,
misalnya `name="juz30halaman582surat78ayat0baris1"`.

Jadi untuk menampilkan satu halaman, pembaca:

1. **menghitung peta halaman lebih dulu** (sebelum baris ditata ulang, karena
   penanda nomor halaman ada di dalam sel-sel baris yang nanti diganti);
2. menata ulang baris mushaf menjadi kepingan kata;
3. menyembunyikan semua bagian halaman lain, menyisakan satu halaman itu saja -
   berikut baris penanda halamannya sendiri.

Penyembunyian memakai `style.setProperty('display', 'none', 'important')`, karena
aturan `display: flex !important` pada kepingan kata akan mengalahkan gaya sebaris
tanpa `!important`.

### Halaman Buku PDF (`buku.html`)

Menu **Buku PDF per halaman** di beranda membuka buku cetak **Risalah Al Qubba**
dalam bentuk PDF: **30 juz, 784 berkas, satu berkas untuk setiap halaman**.

- Tiap juz punya kartu sendiri (bisa dibuka-tutup) berisi tombol nomor halaman
  dan satu tombol **Unduh PDF Juz N lengkap**.
- Ada juga deretan chip 1-30 untuk melompat cepat ke juz tertentu
  (`buku.html#buku-30` langsung membuka Juz 30).
- Tautan PDF mengarah ke `../aqubba/pdf/aqubba/juz-NN/hal-NN.pdf` dan terbuka di
  tab baru, jadi aplikasi tetap terbuka.
- Halaman ini **tidak** di-cache service worker (PDF-nya di luar cakupan PWA),
  tetapi kerangka halamannya ikut di-precache.

Berkas PDF-nya sendiri dibuat dari 30 PDF buku per juz (`q01.pdf`-`q30.pdf`)
yang dipecah per halaman memakai **pdf-lib**; lihat `arqubba/pdf/aqubba/index.html`
dan penjelasan di bagian akhir README ini.

### PWA

- `app.webmanifest` - nama "Sayamuslim - ALQUBBA", `display: standalone`,
  **`orientation: portrait`**, tema `#14503f`, ikon 192/512 dan ikon maskable,
  serta pintasan (shortcut) ke Juz 1 dan Juz 30.
- Ikon dibuat dari medali tengah sampul ALQUBBA (`isi-apk/assets/qubba/img/logo.jpg`),
  digambar ulang dengan kanvas: 192, 512, 512 maskable, 180 (apple-touch), 32 px.
- `sw.js` - service worker:
  - **precache** 19 berkas inti (kerangka, gaya, skrip, ikon, font `aqqc5a.woff`,
    bingkai halaman, logo);
  - navigasi memakai **network-first** dengan cadangan cache dan `index.html`;
  - berkas lain (termasuk `juzN.html`) memakai **cache-first + perbarui di latar**,
    jadi juz yang pernah dibuka bisa dibaca lagi tanpa internet.
- Tombol **Pasang** muncul otomatis lewat `beforeinstallprompt`, dan ikut
  disembunyikan kalau aplikasi sudah berjalan dalam mode terpasang.

### Memasang di HP

1. **Sudah online (disarankan)** - pasang aplikasinya di server ber-HTTPS, lalu
   buka alamatnya di Chrome (Android) atau Safari (iPhone).
   - Android/Chrome: ketuk **Pasang** di beranda, atau menu tiga titik -
     *Tambahkan ke Layar utama*.
   - iPhone/Safari: **Bagikan** - *Tambahkan ke Layar Utama*.
2. **Dari komputer sendiri** - `http://localhost/sayamuslim/` juga bisa dipasang
   di Chrome komputer, tetapi **belum bisa** dipasang dari HP lewat alamat LAN
   biasa (`http://192.168.x.x/...`), karena PWA mensyaratkan HTTPS atau localhost.

### Pengujian yang sudah dilakukan

Diuji otomatis dengan Chrome headless (DevTools Protocol) pada layar **390 x 844**
(HP portrait) - **24 pemeriksaan, semuanya lulus, 0 galat JavaScript**:

**Beranda**
- 30 tombol juz, kartu **Per Halaman** ada, `data/halaman.js` termuat, batas isian
  lompat halaman = 604;
- mengisi nomor 582 di kartu itu membuka `baca.html?hal=582`.

**Tampilan per halaman (`?hal=582`)**
- judul "Halaman 582", memuat `juz30.html`, pemilih berisi **604 halaman**;
- hanya **1 dari 23** blok halaman yang tampil, dan baris yang tampil hanya 15 dari
  345 baris juz itu - jadi memang satu halaman mushaf;
- blok yang tampil benar-benar halaman 582 (dicek lewat penandanya);
- navigasi Sebelum = Halaman 581, Berikut = Halaman 583;
- lebar isi 390 px (pas) dan font `aqqc5a` termuat.

**Lintas juz dan tepi**
- halaman 22 otomatis membuka `juz2.html`, navigasi 21/23, tetap satu halaman tampil;
- halaman 1: tombol Sebelum dinonaktifkan; halaman 604: tombol Berikut dinonaktifkan.

**Tampilan per juz**
- tombol **Juz/Hlm** memindahkan cara tampil; di mode juz seluruh 23 halaman Juz 30
  tampil kembali dan pemilih berisi 30 juz.

**PWA**
- manifest terbaca tanpa galat, ikon 192 dan 512 ada, `display: standalone`,
  `orientation: portrait`, dan **Chrome melaporkan 0 galat kelayakan pasang**;
- **uji offline**: jaringan dimatikan, `baca.html?hal=582` tetap terbuka lengkap
  dari cache (satu halaman, 15 baris).

Sebelumnya sudah diuji pula Juz 1, 2, 15, dan 29 satu per satu: semuanya tampil
penuh, lebar pas, font termuat, tanpa galat. Juga diperiksa bahwa gaya
`display: flex !important` pada kepingan kata **tidak bisa** disembunyikan dengan
gaya sebaris biasa - penyembunyian halaman harus memakai `!important`.

Tangkapan layar bukti ada di `tangkapan/`: `pwa-1-beranda.png`,
`pwa-2-baca-juz30.png`, `pwa-6-per-halaman.png`, `pwa-4-offline.png`,
`pwa-5-baca-juz1.png`.

---

## Bagian 2 - Uraian sayamuslim.apk

Berkas `sayamuslim.apk` (10.051.236 byte) adalah ZIP dengan **245 entri**. Isinya
disimpan di `isi-apk/` **dengan susunan folder aslinya di dalam APK** tetap utuh.

| Bagian | Berkas | Keterangan |
|---|---|---|
| `assets/` | 68 | isi web (HTML, gambar, font, jQuery) |
| `res/` | 169 | sumber daya Android: layout XML, gambar, **110 audio MP3** |
| `META-INF/`, `org/` | 5 | tanda tangan paket dan pustaka |
| lain-lain | 3 | `AndroidManifest.xml`, `classes.dex`, `resources.arsc` |

### 46 berkas HTML

- **`assets/qubba/` - 41 berkas** (aplikasi utama ALQUBBA): `index.html` (tentang),
  `juz.html` (daftar 30 juz), **`juz1.html` ... `juz30.html`** (~1,4 MB masing-masing),
  `ayat.html`, `halaman.html`, `namasurat.html`, `player.html`, `surat.html`,
  3 versi demo, dan `jquery.js`.
- **`assets/` - 3 berkas**: `index.html`, `isi.html`, `khumus30.html`.
- **`assets/khumus/` - 2 berkas**: `isi.html`, `khumus30.html`.

### Perbaikan jalur font

**32 berkas** merujuk font lewat jalur Android:

    file:///android_asset/fonts/aqqc5a.woff   ->   fonts/aqqc5a.woff

Tanpa perbaikan ini tulisan Arab tidak tampil saat dibuka di peramban. Berkas
`fonts/aqqc5a.woff` (161 KB) tersedia di `assets/`, `assets/qubba/`, dan
`assets/khumus/` sesuai kebutuhan masing-masing berkas.

### Catatan penting soal teks Arabnya

Teks Arab di dalam HTML itu **disimpan dengan encoding lama, bukan Unicode Arab**.
Dibaca sebagai teks biasa hasilnya rusak:

    ǡöĀUȥńÔÍ( Ğ/Ā6ØĪk Berita besar Surat ...

Yang membuatnya menjadi huruf Arab adalah font pemetaan khusus `aqqc5a.woff`.
Jadi **jangan menyalin teks** dari berkas itu kalau butuh teks Arab yang benar -
pakai sumber Unicode (misalnya basis data aplikasi Ngaji). Di layar tetap tampil
benar selama fontnya ikut termuat.

### Struktur folder

    sayamuslim/
    |- index.html            beranda aplikasi PWA (portrait)
    |- baca.html             halaman baca mushaf (per juz & per halaman)
    |- buku.html             buku PDF per halaman (30 juz, 784 berkas)
    |- katalog.html          katalog 46 berkas HTML
    |- app.webmanifest       manifest PWA
    |- sw.js                 service worker (precache + tahan offline)
    |- gaya/
    |   |- aplikasi.css      gaya kerangka aplikasi
    |   \- mushaf.css        gaya yang disuntikkan ke halaman mushaf
    |- js/
    |   |- aplikasi.js       beranda: kisi juz, pendaftaran SW, tombol pasang
    |   |- baca.js           halaman baca: suntik gaya + tata ulang baris mushaf
    |   \- buku.js           halaman buku: buka kartu juz dari alamat
    |- data/halaman.js       peta 604 halaman mushaf ke juz (dari halaman.html)
    |- ikon/                 ikon 192, 512, maskable, apple-touch, favicon
    |- isi-apk/              hasil uraian APK (susunan asli)
    |- alat/                 skrip uji & pembuat ikon
    |- tangkapan/            tangkapan layar pengujian
    |- README.md             berkas ini
    \- sayamuslim.apk        salinan APK asli

---

## Menguraikan ulang APK

APK adalah berkas ZIP biasa:

    Add-Type -AssemblyName System.IO.Compression.FileSystem
    [System.IO.Compression.ZipFile]::ExtractToDirectory('sayamuslim.apk', 'isi-apk')

Skrip yang dipakai saat menguraikan dan menguji ada di folder `alat/`.

## Kemungkinan pengembangan lanjutan

- Memasang di subdomain ber-HTTPS, misalnya `sayamuslim.kolegaweb.com`, supaya
  bisa benar-benar dipasang dari HP.
- Menambahkan penanda halaman terakhir dibaca dan riwayat bacaan.
- Memasukkan pemutar audio (110 berkas MP3 di `res/raw`) ke dalam aplikasi web.
- Mode gelap dan penanda ayat.

---

## Daring (publik)

Aplikasi ini sudah dipasang di server dan bisa dibuka siapa saja:

    https://quran.kolegaweb.com/

| Alamat | Isi |
|---|---|
| https://quran.kolegaweb.com/ | beranda aplikasi Sayamuslim (PWA) |
| https://quran.kolegaweb.com/baca.html?juz=30 | baca per juz |
| https://quran.kolegaweb.com/baca.html?hal=582 | baca per halaman |
| https://quran.kolegaweb.com/buku.html | buku PDF per halaman |
| https://quran.kolegaweb.com/buku/ | katalog 784 PDF per halaman |
| https://quran.kolegaweb.com/katalog.html | katalog berkas HTML hasil uraian APK |

- **VPS**: 202.10.34.73, nginx 1.18, sertifikat Let's Encrypt untuk
  quran.kolegaweb.com (dipasang 2 Oktober 2026, berlaku 89 hari, diperbarui otomatis).
- **Letak berkas**: /var/www/quran.kolegaweb.com/public_html (341 MB, 1.079 berkas).
  PDF ada di dalam public_html/buku/.
- HTTP otomatis dialihkan ke HTTPS (301). Service worker dan manifest tidak
  di-cache lama supaya pembaruan aplikasi cepat sampai ke pengguna.
- Karena sudah HTTPS, PWA-nya **benar-benar bisa dipasang di HP**
  (Chrome: menu - Pasang aplikasi; iPhone: Bagikan - Tambahkan ke Layar Utama).

### Dua tampilan halaman baca

Tombol **Mushaf / Terjemah** di bilah kedua halaman baca mengganti cara penyajian:

| Tampilan | Isi |
|---|---|
| **Mushaf** (bawaan) | berkas `juzN.html` **asli apa adanya** - tata letak mushaf lengkap dengan **warna tajwid** dari atribut `<font color="...">` milik berkas aslinya. Halaman diperkecil otomatis agar pas lebar layar; tombol A-/A+ memperbesar (bisa digeser mendatar). |
| **Terjemah** | baris mushaf ditata ulang menjadi kepingan kata + arti per kata. Warna tajwid tetap dipertahankan. |

Warna tajwid di berkas asli ada **25 warna berbeda** (mis. `#FF00FF` magenta 2.152 kali, `#CC0000` merah tua, `#FF9900` oranye, `#0066FF` biru, `#39B552` hijau). Sebelum ini warna itu hilang karena penataan ulang baris dan aturan CSS `font[color] { color: inherit }` - keduanya sudah diperbaiki:

- `js/baca.js` memakai `innerHTML` (bukan `textContent`) saat memindahkan kata, sehingga penanda warna ikut terbawa;
- `gaya/mushaf.css` tidak lagi menimpa warna teks.