Work offline

A Qur’an app is expected to work on a plane. This page is the sizes of what each block ships, so you can decide what goes in the bundle, what is fetched once and cached, and what never belongs on a phone at all.

The rule of thumb

One edition of the text plus its font is about 3.4 MB and answers every question about the words. A rendered page is 38 KB in the engine, 196–613 KB as SVG. Ship the text; ship pages by demand; never ship the 50 MB word index.

What one file weighs

Measured from the copies this site serves:

The rest, from the source repositories at the commits pinned in public/demo/SOURCES.json, on 11 September 2026:

Decide what goes where

1. Choose the unit of download

   Quran Text has no per-surah file: a surah, a page and a juz are slices of one array, so the smallest download for one ayah is the whole edition, and at 1.9–3.1 MB that is the right unit. For rendered pages the unit is one page (NNN.qvp in the engine, NNN.svg.br for Quran SVG) and a juz is a sensible batch.

2. Verify every download against its digest

   Each block publishes the digest differently, and the check is one hash either way:

   Block	Where the digest is
   Quran Text	data/manifest.json — files[].sha256 for every emitted file
   Quran Engine	quran-engine-pages-hafs-kfgqpc.tar.gz.sha256 beside the release asset
   Quran SVG Elements	CHECKSUMS.txt inside the bundle — sha256sum -c CHECKSUMS.txt
   Quran Tajweed	edition.sha256 inside the annotations file names the text the spans belong to

   // After fetching data/mushaf/warsh.json into `bytes`, against data/manifest.json
   const expected = manifest.files.find((f) => f.path === "data/mushaf/warsh.json").sha256;
   const hash = await crypto.subtle.digest("SHA-256", bytes);
   const actual = [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, "0")).join("");
   if (actual !== expected) throw new Error("warsh.json: digest mismatch — do not cache");
   // expected: 2134d90016ecd26543ca6eaef21427227ec7641d667b0fc14fbb8e4c3f6dbd3a
   

   Cache under the digest, not under the URL — a cache key names everything the value depends on (Engineering, rule 8.1). A file that hashes the same is the same file; a file that hashes differently is a new edition of the text, and everything derived from the old one (search caches, tajwīd offsets, word-level bookmarks) is suspect.

3. Keep the provenance with the cache

   Store provenance.text.sha256, the provenance of each cached muṣḥaf, beside your own data. It lets a bookmark written against one build be checked against another; see Store bookmarks and progress.

4. Check for updates, and know what the check does today

   The JavaScript library has an update check built in. It never throws and never rejects: it resolves to null whenever it cannot get an answer.

   const status = await m.checkForUpdate();   // default url: Mushaf.VERSION_URL, 5 s timeout
   // { edition, upToDate, localSource, latestSource, dataset, downloadUrl } — or null
   

   It resolves to null in production right now

   Mushaf.VERSION_URL is https://quran.ws/version, and the result’s downloadUrl is built on https://quran.ws/files/. On 11 September 2026 both paths return an HTML page, not a format: "quran-version" document, so checkForUpdate() returns null for every edition. Treat null as “unknown”, not as “up to date”, and do not build an update flow on this until the endpoint exists. Recorded in docs/dx/quran-text.md.

   Until then, the working update check is the one in step 2: re-fetch data/manifest.json, compare the digest of the file you hold, and download when it differs.

What is not offline

Quran PNG is an HTTP service and has no offline form. Inside an app that already holds engine pages, page.cropSvg() gives the same artwork with no network.