feat(quran): download ayah-marker ornament pack (schema-2 manifest)

Author: F2had

src/app/(tabs)/quran.tsx

@@ -148,6 +148,13 @@ const QuranScreen = () => {
     }, [setSheetReturnAyah])
   );
 
+  // Ensure the edition's ayah-marker frames are installed (covers editions added
+  // before the ornament pack shipped). Idempotent + tiny (~20KB); no-ops once on
+  // disk. New downloads already include markers via the edition download.
+  useEffect(() => {
+    if (showReader) QuranDownload.ensureMarkersInstalled(currentVersion);
+  }, [showReader, currentVersion]);
+
   // First time the reader is shown, run the gesture walkthrough.
   useEffect(() => {
     // eslint-disable-next-line react-hooks/set-state-in-effect

src/services/quran-download-plan.ts

@@ -2,7 +2,7 @@
 // Images and meta/bounds are versioned independently; we track both installed
 // versions to re-download only the leg that changed and keep bounds geometry
 // matched to its render.
-export type InstalledVersions = { images?: string; meta?: string };
+export type InstalledVersions = { images?: string; meta?: string; markers?: string };
 
 // Decide which legs to (re)download. Meta is "ok" only when its own version
 // matches AND the images it was built against (`requiresImages`) are the ones

src/services/quran-download.ts

@@ -16,7 +16,7 @@ import { QuranManifestService } from "@/services/quran-manifest";
 import { planEditionDownload, type InstalledVersions } from "@/services/quran-download-plan";
 import { useQuranStore } from "@/stores/quran";
 import { AppLogger } from "@/utils/appLogger";
-import type { DownloadProgress } from "@/types/quran";
+import type { DownloadProgress, QuranManifestVersion } from "@/types/quran";
 
 const log = AppLogger.create("quran-download");
 
@@ -125,6 +125,12 @@ const getVersionDir = (version: MushafVersion): Directory => {
   return new Directory(Paths.document, `quran/${version}`);
 };
 
+// Where the ayah-marker medallion frames live (AyahMarker reads them here);
+// populated by extracting the edition's ayah-marker ornament pack.
+const getMarkersDir = (version: MushafVersion): Directory => {
+  return new Directory(Paths.document, `quran/${version}/markers`);
+};
+
 // Dark-theme images live in a sibling directory so they can be downloaded and
 // deleted independently of the main (light) bundle.
 const getDarkVersionDir = (version: MushafVersion): Directory => {
@@ -315,6 +321,57 @@ const downloadAndExtractBundle = async (
   }
 };
 
+// Download + extract the edition's default ayah-marker frame pack into the markers
+// dir, when absent or out of date. Self-contained + non-fatal: any failure is
+// logged and swallowed so the caller's edition flow proceeds (just without markers).
+const ensureAyahMarkers = async (
+  active: ActiveDownload,
+  version: MushafVersion,
+  manifestVersion: QuranManifestVersion
+): Promise<void> => {
+  try {
+    const pack = await QuranManifestService.getAyahMarkerPack(manifestVersion);
+    if (!pack || active.cancelled) return;
+    const markersDir = getMarkersDir(version);
+    const haveFrames = new File(markersDir, "marker-sepia.png").exists;
+    if (haveFrames && readInstalled(version).markers === pack.version) return;
+
+    const outcome = await downloadAndExtractBundle(active, {
+      url: pack.url,
+      sizeBytes: 0,
+      dir: markersDir,
+      zipName: `quran-${version}-markers.zip`,
+      alreadyOnDisk: false,
+      emit: () => {},
+    });
+    if (outcome === BundleOutcome.EXTRACTED) {
+      writeInstalled(version, { markers: pack.version });
+      log.d("Download", `Installed ayah-marker pack ${pack.version} for ${version}`);
+    }
+  } catch (error) {
+    log.e(
+      "Download",
+      `Ayah-marker pack failed for ${version} (markers absent)`,
+      error instanceof Error ? error : undefined
+    );
+  }
+};
+
+// Opportunistic, idempotent marker fetch for an already-installed edition (the
+// edition download covers fresh installs; this catches editions installed before
+// the ornament pack existed, or a pack version bump). Cheap: no-ops once the
+// current pack is on disk. Runs in its own lightweight context (not a tracked
+// download) so it never shows progress chrome.
+const ensureMarkersInstalled = async (version: MushafVersion): Promise<void> => {
+  const manifestVersion = await QuranManifestService.getVersionInfo(version);
+  if (!manifestVersion) return;
+  await ensureAyahMarkers(
+    { controller: new AbortController(), cancelled: false, promise: Promise.resolve() },
+    version,
+    manifestVersion
+  );
+};
+
 const start = (version: MushafVersion): Promise<void> =>
   beginDownload(activeDownloads, version, doStart);
 
@@ -431,6 +488,11 @@ const doStart = async (version: MushafVersion, active: ActiveDownload): Promise<
     }
     if (plan.needMeta) writeInstalled(version, { meta: manifestVersion.meta.version });
 
+    // 3) Ayah-marker ornament (tiny ~20KB): the edition's default medallion frames
+    // the reader overlays on each ayah. Fetched when missing or its version changed.
+    // Non-fatal — a failure leaves the edition usable (text/images), just no markers.
+    await ensureAyahMarkers(active, version, manifestVersion);
+
     // Complete only once BOTH legs have landed.
     clearResume(version);
     store.updateDownloadState(version, { status: DownloadStatus.COMPLETE });
@@ -656,6 +718,7 @@ const checkDiskSpace = (requiredMB: number): { available: boolean; availableMB:
 
 export const QuranDownload = {
   start,
+  ensureMarkersInstalled,
   startDark,
   deleteDark,
   pause,

src/services/quran-manifest.ts

@@ -74,6 +74,21 @@ const getMetaUrl = async (version: QuranManifestVersion): Promise<string | null>
   return manifest ? assetUrl(manifest, version.meta.url) : null;
 };
 
+// The edition's default ayah-marker ornament pack (medallion frames) + its version.
+// Null when the manifest ships no ayah-marker ornaments for this edition.
+const getAyahMarkerPack = async (
+  version: QuranManifestVersion
+): Promise<{ url: string; version: string } | null> => {
+  const manifest = await fetchManifest();
+  const group = manifest?.ornaments?.ayahMarker;
+  if (!manifest || !group) return null;
+  const optionId = group.defaultByEdition?.[version.id] ?? group.default;
+  const option =
+    group.options.find((o) => o.id === optionId) ??
+    group.options.find((o) => o.editions?.includes(version.id));
+  return option ? { url: assetUrl(manifest, option.url), version: option.version } : null;
+};
+
 const getImagesSizeBytes = (version: QuranManifestVersion, dark = false): number =>
   (dark ? version.images.dark?.bytes : version.images.light.bytes) ?? 0;
 
@@ -118,6 +133,7 @@ export const QuranManifestService = {
   getContent,
   getImagesUrl,
   getMetaUrl,
+  getAyahMarkerPack,
   getImagesSizeBytes,
   getMetaSizeBytes,
   getTotalSizeBytes,

src/types/quran.ts

@@ -145,12 +145,38 @@ export type QuranContent = {
   sha256: string;
 };
 
+// A selectable ornament style (e.g. ayah-marker frames) as a downloadable pack.
+export type QuranOrnamentOption = QuranAsset & {
+  id: string;
+  version: string;
+  resolution?: number;
+  // Editions this option applies to (the marker artwork differs per edition).
+  editions?: string[];
+  preview?: string;
+};
+
+export type QuranOrnamentGroup = {
+  default: string;
+  // Per-edition default option id, overriding `default`.
+  defaultByEdition?: Record<string, string>;
+  options: QuranOrnamentOption[];
+};
+
+// Selectable style packs overlaid on the reader, keyed off bounds positions.
+export type QuranOrnaments = {
+  ayahMarker?: QuranOrnamentGroup;
+  surahFrame?: QuranOrnamentGroup;
+  pageHolder?: QuranOrnamentGroup;
+};
+
 export type QuranManifest = {
   manifestSchema: number;
   baseUrl: string;
   editions: QuranManifestVersion[];
   content: QuranContent;
-  // `ornaments` exists in the manifest but is deferred (app uses bundled ornaments).
+  // Style packs (ayah-marker frames etc.) downloaded per edition; the ayah-marker
+  // default pack carries the medallion frames the reader overlays on each ayah.
+  ornaments?: QuranOrnaments;
 };
 
 export type QuranLibraryTab = "index" | "highlights" | "bookmarks" | "khatmah" | "guide";