@quran.ws/qvp-react-native 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# @quran.ws/qvp-react-native
+
+React Native wrapper for the QVP vector mushaf engine. Android-first: a native view
+(`<QvpPageView />`) hosting the Kotlin library's `QvpPageView` (`net.quranpedia.qvp`,
+`packages/android/qvp`, JNI over `crates/qvp-ffi/include/qvp.h`) plus a promise-based module
+(`QvpModule`) for queries. The wrapper is *thin*: no hit-testing, layout or styling logic in JS or
+in the module — it marshals props/targets/selectors and reconciles declarative arrays against engine
+handles. Names follow `docs/API.md`. **The package ships no page data.**
+
+## Install
+
+```sh
+npm install @quran.ws/qvp-react-native        # or a file:/git dependency inside the monorepo
+```
+
+Android needs the Kotlin library. Preferred: include it as a Gradle project in your app's
+`android/settings.gradle` (this is what `../example` does):
+
+```groovy
+include ':qvp'
+project(':qvp').projectDir = file('<repo>/packages/android/qvp')   // e.g. '../../../android/qvp'
+```
+
+The module then depends on `project(':qvp')`. If `:qvp` is not included, the module compiles the
+library's Kotlin + JNI sources itself from `qvpAndroidDir` (Gradle property; default
+`../../../android/qvp`, right for the monorepo). Either way the engine comes from
+`packages/android/qvp/prebuilt/<abi>/libqvp_ffi.a` — produce it once with
+`scripts/build-engine-android.sh` from the repo root.
+
+Requirements: RN ≥ 0.76 (legacy view manager / native module through the interop layer, verified on
+0.87 with the New Architecture), minSdk 24, NDK 27, CMake 3.22.
+
+Page data: `cargo run -p qvp-convert --release -- batch pages dist/pages` → `NNN.qvp`,
+`NNN.words.json`, `atlas.qva`. Put them wherever you like (assets, files dir, downloads) and pass
+URIs: `asset://pages/042.qvp`, `file:///…`, `/abs/path`, or `base64:…`.
+
+## The view
+
+```tsx
+import { QvpPageView, useQvp, Sel, T, LAYER, KIND, DECO, rgba } from '@quran.ws/qvp-react-native';
+
+const qvp = useQvp();
+<QvpPageView
+  ref={qvp.ref}
+  style={{ flex: 1 }}
+  pageUri="asset://pages/042.qvp"
+  wordsUri="asset://pages/042.words.json"                       // optional sidecar (rasm_imlai/qpc/rasm/search forms)
+  padTop={12} padBottom={12} padSide={8}                        // dp
+  lineSpacing={1} lineGap={0} fillHeight={false}                // engine layout knobs (page units for lineGap)
+  paperColor="#fffdf7" defaultInk="#231f20"
+  theme={{ diacritics: '#1a73e8', dots: '#c62828', waqf: '#0a7d32', ms: 200 }}     // page.theme(...) — one handle
+  styles={[
+    { id: 'hide-marks', selector: Sel.kind(KIND.MARK), hide: true },                  // page.hide(sel)
+    { id: 'gold', selector: Sel.deco(DECO.AYAH_MARK), color: '#b8860b', ms: 300, layer: LAYER.THEME + 1 },
+    { id: 'mark', selector: Sel.wordMark(12, 1), color: '#ef6c00', ms: 200, layer: LAYER.TOP },  // 2nd diacritic of word 12
+    { id: 'ayah', target: '2:255', color: '#0a7d32' },                                 // page.styleTarget(...)
+  ]}
+  highlights={[
+    { id: 'sel', target: T.word(12), style: { mode: 'both', ink: '#1a73e8', band: rgba('#1a73e8', 0.18), radius: 1.5, ms: 250, layer: LAYER.SELECTION } },
+    { id: 'search', target: T.words([3, 9, 41]), style: { mode: 'both', ink: '#c62828', band: rgba('#c62828', 0.12), height: 'ink' } },
+  ]}
+  mask={{ target: '2:255', mode: 'hide' }}                       // or 'block' | 'blur' (+ blockColor, padX, padY, radius)
+  reveal={{ lit: 2, grey: '#c9c4b8', ink: '#231f20', ms: 150, at: 3 }}   // greyed page; `at` drives revealGoto
+  onWordTap={({ word, hit }) => …}      // word: {idx, surah, ayah, word, line, …, text, wordKey, aid, forms, label, paths[]}
+  onDecoTap={({ deco, hit }) => …}      // ayah markers, banners, basmalah, rosettes, sajdah signs
+  onEmptyTap={() => …}
+  onSelectionChanged={({ words, text, citation, textWithCitation }) => …}   // long-press-drag selection
+  onPageLoad={info => …}                // {page, width, height, nLines, nAyahs, nWords, nPaths, nDecos, forms, loadMs, bytes}
+  onRevealChanged={({ steps, at }) => …}
+  onError={({ message }) => …}
+/>
+```
+
+Reconciliation: each `highlights` entry maps to one engine handle. A new id → `highlight`; a changed
+`target` → `rehighlight` (the band slides); a changed `style` → `restyleHighlight`; a removed id →
+`unhighlight` (fades out). `styles` works the same over `style` / `styleTarget` / `hide` / `restyle` /
+`unstyle`; `theme` is one handle; `mask` re-applies `maskOptions` + `mask` when the object changes
+(`null` → `unmask`); `reveal` calls `revealStart` when its config changes and `revealGoto` when `at`
+changes (`null` → `revealStop`). When `pageUri` changes, the old page is freed and every declarative
+prop is re-applied to the new page.
+
+Gestures are the Kotlin view's: tap → gap-aware `hitTestViewEx` → `onWordTap` / `onDecoTap` /
+`onEmptyTap`; long-press-drag → engine `select` with a band in `LAYER.SELECTION`; pinch / pan;
+double-tap resets. Props `selectionEnabled`, `zoomEnabled`, `hitMaxDistance`, `selectionBand`.
+
+Colours: `'#rgb' | '#rrggbb' | '#rrggbbaa' | 0xRRGGBBAA` (`css()` / `rgba(c, alpha)` helpers).
+Targets: `'page' | '2:255' | '2:255:3' | '2:255-257' | 'line:7' | 'surah:2' | wordIdx | [idx…] | T.*`.
+Selectors: `Sel.page/path/wordPath/wordMark/wordMarkNamed/wordBody/wordMarks/word/ayah/line/mark/category/family/kind/deco/decoIdx`.
+
+## The module
+
+Everything takes the view's react tag (`findNodeHandle`) — or use the bound forms:
+`useQvp()` returns `{ ref, tag, ...api }`, and the component ref exposes the same `api`.
+
+```ts
+const qvp = useQvp();
+await qvp.info(); qvp.words(); qvp.word(i); qvp.ayahs(); qvp.lines(); qvp.decos();
+await qvp.search('الرحمان', { mode: 'includes' });     // [{word, wordKey, text, index, loose}]
+await qvp.text('2:255', { form: 'search', wordSep: ' ' });
+await qvp.resolve('line:7'); qvp.findWord(2, 255, 3); qvp.wordForm(i, 'rasm_imlai'); qvp.hasForm('qpc');
+await qvp.attachWords(jsonString);                      // when you do not use the wordsUri prop
+await qvp.surahs(); qvp.divisions(); qvp.markers(); qvp.rosettes(); qvp.sajdahs(); qvp.ayahKeys();
+await qvp.ayahWordCount(2, 255); qvp.reciteMap(2, 255, 4); qvp.wordLabel(i); qvp.ayahLabel(ai);
+await qvp.citation([12, 13, 14]);
+await qvp.cropSvg('2:255', { pad: 3, keepMarkers: true, background: '#fffdf7' }); qvp.cropBox(target);
+await qvp.select(anchor, focus); qvp.clearSelection(); qvp.selection(); qvp.selectionText('rasm_uthmani', true);
+await qvp.revealNext(1); qvp.hideBack(1); qvp.revealWord(i); qvp.hideWord(i); qvp.revealAll(); qvp.hideAll();
+await qvp.maskHidden(); qvp.maskWords(); qvp.revealSteps(); qvp.revealAt(); qvp.revealStepOf(i);
+await qvp.hitTestViewEx(x, y, { maxDistance: 6 }); qvp.wordBoxView(i); qvp.currentLayout(); qvp.relayout(); qvp.resetView(); qvp.stats();
+
+// engine-wide (Qvp.*)
+await Qvp.strip(s); Qvp.fold(s); Qvp.normalize(s); Qvp.looseKey(s);       // = Qvp.arabic(kind, s)
+await Qvp.gapToFill(pageW, pageH, lines, viewW, viewH); Qvp.wastedFraction(...)
+Qvp.markName(7); Qvp.kindName(1); Qvp.categoryName(1); Qvp.familyName(3); Qvp.version
+
+// atlas (cross-page)
+const atlas = await QvpAtlas.load('asset://pages/atlas.qva');
+await atlas.pageOf(2, 255); atlas.pageRange(42); atlas.surah(36); atlas.surahs(); atlas.pageOfSurah(36);
+await atlas.juz(30); atlas.hizb(3); atlas.rubuAlHizb(7); atlas.juzAt(2, 255); atlas.divisionAt('hizb', 2, 255);
+await atlas.pagesOfJuz(30); atlas.findSurah('cow' | 'البقرة' | '2'); atlas.free();
+// tag-level equivalents: Qvp.atlasPageOf(id, s, a), Qvp.atlasFindSurah(id, text), Qvp.atlasPagesOfJuz(id, n), Qvp.atlasJuzAt(id, s, a), …
+```
+
+All page calls run on the UI thread (where the view draws), so the engine is never touched from two
+threads. Only `maskHidden`, `unmask` (via the `mask` prop), `revealNext` etc. mutate state; queries are
+microseconds.
+
+## Layout of this package
+
+```
+android/build.gradle                       library module; depends on project(':qvp') or compiles its sources
+android/src/main/java/net/quranpedia/qvp/rn/
+  QvpRnPageView.kt      QvpPageView subclass: page loading, prop → handle reconciliation, events
+  QvpPageViewManager.kt SimpleViewManager<QvpRnPageView> (props, events, commit after each prop batch)
+  QvpModule.kt          ReactContextBaseJavaModule: page queries by react tag, engine helpers, atlas
+  Marshal.kt            JS shapes ↔ Kotlin types (targets, selectors, styles, records)
+  QvpPackage.kt
+src/index.tsx                              typed API: <QvpPageView/>, useQvp(), Qvp, QvpAtlas, Sel, T, constants
+```
+
+## iOS — TODO
+
+Not implemented (no macOS in the build environment). The iOS side mirrors the Android module over the
+same `qvp.h`: a Swift `QvpPage`/`QvpAtlas` over `libqvp_ffi.a` (build with
+`cargo build -p qvp-ffi --release --target aarch64-apple-ios[-sim]`), a `UIView` renderer with the
+same draw order (highlight bands → cached base ink → styled ink → mask boxes, `tick(now)` per
+`CADisplayLink` frame), an `RCTViewManager` exposing the props above with the same reconciliation, and
+an `RCTBridgeModule` with the same method names. `src/index.tsx` needs no changes.

package/android/build.gradle

@@ -0,0 +1,53 @@
+// @quran.ws/qvp-react-native — Android module. Thin: marshalling + handle reconciliation over the Kotlin
+// library `net.quranpedia.qvp` (packages/android/qvp), which is JNI over crates/qvp-ffi/include/qvp.h.
+//
+// Linking the Kotlin library, two ways:
+//   1. (preferred) the app's settings.gradle includes it as a Gradle project:
+//        include(":qvp"); project(":qvp").projectDir = file("<repo>/packages/android/qvp")
+//      and this module depends on `project(":qvp")`.
+//   2. otherwise this module compiles the library's Kotlin + JNI sources straight from `qvpAndroidDir`
+//      (gradle property; default: ../../../android/qvp inside the monorepo). Same code, one AAR.
+buildscript {
+    if (project == rootProject) {
+        repositories { google(); mavenCentral() }
+        dependencies {
+            classpath("com.android.tools.build:gradle:8.7.3")
+            classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.21")
+        }
+    }
+}
+
+apply plugin: "com.android.library"
+apply plugin: "org.jetbrains.kotlin.android"
+
+def safeExtGet(prop, fallback) { rootProject.ext.has(prop) ? rootProject.ext.get(prop) : fallback }
+def qvpProject = findProject(":qvp")
+def qvpDir = file(rootProject.findProperty("qvpAndroidDir") ?: "$projectDir/../../../android/qvp")
+
+android {
+    namespace "net.quranpedia.qvp.rn"
+    compileSdk safeExtGet("compileSdkVersion", 35)
+    defaultConfig {
+        minSdkVersion safeExtGet("minSdkVersion", 24)
+        if (qvpProject == null) {
+            externalNativeBuild { cmake { arguments "-DANDROID_STL=none" } }
+            ndk { abiFilters "arm64-v8a", "x86_64", "armeabi-v7a" }
+        }
+    }
+    if (qvpProject == null) {
+        ndkVersion safeExtGet("ndkVersion", "27.2.12479018")
+        externalNativeBuild { cmake { path file("$qvpDir/src/main/cpp/CMakeLists.txt"); version "3.22.1" } }
+        sourceSets { main { kotlin.srcDirs += "$qvpDir/src/main/kotlin"; java.srcDirs += "$qvpDir/src/main/kotlin" } }
+    }
+    compileOptions { sourceCompatibility JavaVersion.VERSION_17; targetCompatibility JavaVersion.VERSION_17 }
+    buildFeatures { buildConfig false }
+}
+kotlin { compilerOptions { jvmTarget = org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17 } }
+
+repositories { google(); mavenCentral() }
+
+dependencies {
+    // version pinned by the React Native Gradle Plugin of the consuming app
+    implementation "com.facebook.react:react-android"
+    if (qvpProject != null) implementation project(":qvp")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android" />

package/android/src/main/java/net/quranpedia/qvp/rn/Marshal.kt

@@ -0,0 +1,191 @@
+package net.quranpedia.qvp.rn
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.WritableArray
+import com.facebook.react.bridge.WritableMap
+import net.quranpedia.qvp.*
+import net.quranpedia.qvp.Target
+
+/**
+ * Marshalling only: JS shapes (docs/API.md) ↔ Kotlin library types. No hit-testing, layout or
+ * styling decisions live here — every call goes to [QvpPage] / [QvpAtlas], which go to the engine.
+ *
+ * Targets from JS: "page" | "2:255" | "2:255:3" | "2:255-257" | "line:7" | "surah:2" | word index |
+ * [word indices] | {kind, a, b, c, words} (kind = QVP_TARGET_* or its name).
+ * Selectors from JS: {kind, a, b, c} (kind = QVP_SEL_* or its name). Colours: '#rgb' | '#rrggbb' | '#rrggbbaa'.
+ */
+object Marshal {
+    // ── colours ──
+    fun color(v: Any?, default: Int): Int = when (v) {
+        null -> default
+        is String -> if (v.isBlank()) default else runCatching { QvpColor.parse(v) }.getOrDefault(default)
+        is Number -> v.toLong().toInt()
+        else -> default
+    }
+    fun colorOrNull(v: Any?): Int? = if (v == null) null else color(v, 0).let { if (it == 0) null else it }
+
+    private fun num(v: Any?): Int? = (v as? Number)?.toInt() ?: (v as? String)?.toIntOrNull()
+    private fun flt(v: Any?, d: Float): Float = (v as? Number)?.toFloat() ?: (v as? String)?.toFloatOrNull() ?: d
+    private fun bool(v: Any?, d: Boolean): Boolean = (v as? Boolean) ?: (v as? Number)?.let { it.toInt() != 0 } ?: d
+    private fun ints(v: Any?): IntArray = when (v) {
+        is Iterable<*> -> v.mapNotNull { num(it) }.toIntArray()
+        is IntArray -> v
+        is Number -> intArrayOf(v.toInt())
+        else -> IntArray(0)
+    }
+
+    private val TARGET_KINDS = listOf("page", "word", "words", "ayah", "ayahRange", "line", "surah", "range")
+    private val SEL_KINDS = listOf("page", "path", "wordPath", "wordMark", "wordMarkNamed", "wordBody", "wordMarks", "word", "ayah", "line", "mark", "category", "family", "kind", "deco", "decoIdx")
+    private fun kindOf(v: Any?, names: List<String>): Int = when (v) {
+        is Number -> v.toInt()
+        is String -> names.indexOf(v).let { if (it >= 0) it else v.toIntOrNull() ?: -1 }
+        else -> -1
+    }
+
+    /** JS target (already converted with toHashMap/toArrayList or a plain value) → [Target]. Unknown → empty word list. */
+    fun target(v: Any?, page: QvpPage?): Target = when (v) {
+        null -> Target.page()
+        is String -> runCatching { Target.parse(v, page) }.getOrElse { Target.words(IntArray(0)) }
+        is Number -> Target.word(v.toInt())
+        is Iterable<*> -> Target.words(ints(v))
+        is IntArray -> Target.words(v)
+        is Map<*, *> -> {
+            val a = num(v["a"]) ?: 0; val b = num(v["b"]) ?: 0; val c = num(v["c"]) ?: 0
+            when (kindOf(v["kind"], TARGET_KINDS)) {
+                0 -> Target.page(); 1 -> Target.word(a); 2 -> Target.words(ints(v["words"] ?: v["a"]))
+                3 -> Target.ayah(a, b); 4 -> Target.ayahRange(a, b, c); 5 -> Target.line(a); 6 -> Target.surah(a); 7 -> Target.range(a, b)
+                else -> Target.words(IntArray(0))
+            }
+        }
+        else -> Target.words(IntArray(0))
+    }
+
+    /** JS selector {kind, a, b, c} → [Selector], or null when malformed. */
+    fun selector(v: Any?): Selector? {
+        val m = v as? Map<*, *> ?: return null
+        val a = num(m["a"]) ?: 0; val b = num(m["b"]) ?: 0; val c = num(m["c"]) ?: 0
+        return when (kindOf(m["kind"], SEL_KINDS)) {
+            0 -> Selector.page(); 1 -> Selector.path(a); 2 -> Selector.wordPath(a, b); 3 -> Selector.wordMark(a, b)
+            4 -> Selector.wordMarkNamed(a, (m["mark"] as? String) ?: QVP_MARKS.getOrElse(b) { "" }, c)
+            5 -> Selector.wordBody(a); 6 -> Selector.wordMarks(a); 7 -> Selector.word(a); 8 -> Selector.ayah(a, b); 9 -> Selector.line(a)
+            10 -> (m["mark"] as? String)?.let { Selector.mark(it) } ?: Selector.mark(a)
+            11 -> Selector.category(a); 12 -> Selector.family(a); 13 -> Selector.kind(a); 14 -> Selector.deco(a); 15 -> Selector.decoIdx(a)
+            else -> null
+        }
+    }
+
+    fun form(v: Any?, d: Form = Form.RASM_UTHMANI): Form = when (v) {
+        is Number -> Form.entries.getOrElse(v.toInt()) { d }
+        is String -> Form.entries.firstOrNull { it.name.equals(v, true) } ?: d
+        else -> d
+    }
+    fun searchMode(v: Any?): SearchMode = when (v) {
+        is Number -> SearchMode.entries.getOrElse(v.toInt()) { SearchMode.INCLUDES }
+        is String -> SearchMode.entries.firstOrNull { it.name.equals(v, true) } ?: SearchMode.INCLUDES
+        else -> SearchMode.INCLUDES
+    }
+    fun maskMode(v: Any?): MaskMode = when (v) {
+        is Number -> MaskMode.entries.getOrElse(v.toInt()) { MaskMode.HIDE }
+        is String -> MaskMode.entries.firstOrNull { it.name.equals(v, true) } ?: MaskMode.HIDE
+        else -> MaskMode.HIDE
+    }
+    fun division(v: Any?): Division = when (v) {
+        is Number -> Division.entries.getOrElse(v.toInt()) { Division.JUZ }
+        is String -> Division.entries.firstOrNull { it.name.equals(v, true) } ?: Division.JUZ
+        else -> Division.JUZ
+    }
+
+    /** {mode, ink, band, height, padX, padY, radius, seam, ms, layer} → [QvpHighlightStyle] (missing keys keep the library defaults). */
+    fun highlightStyle(v: Any?): QvpHighlightStyle {
+        val m = v as? Map<*, *> ?: return QvpHighlightStyle()
+        val d = QvpHighlightStyle()
+        val mode = when (val x = m["mode"]) { is Number -> HighlightMode.entries.getOrElse(x.toInt()) { d.mode }; is String -> HighlightMode.entries.firstOrNull { it.name.equals(x, true) } ?: d.mode; else -> d.mode }
+        val height = when (val x = m["height"]) { is Number -> BandHeight.entries.getOrElse(x.toInt()) { d.height }; is String -> BandHeight.entries.firstOrNull { it.name.equals(x, true) } ?: d.height; else -> d.height }
+        return QvpHighlightStyle(mode = mode, ink = color(m["ink"], d.ink), band = color(m["band"], d.band), height = height, padX = flt(m["padX"], d.padX), padY = flt(m["padY"], d.padY),
+            radius = flt(m["radius"], d.radius), seam = flt(m["seam"], d.seam), transitionMs = num(m["ms"] ?: m["transitionMs"]) ?: d.transitionMs, layer = num(m["layer"]) ?: d.layer)
+    }
+    /** {ink, diacritics, dots, waqf, sifr, ayahMark, numeral, headers, marks: {name: colour}, ms} → [QvpTheme]. */
+    fun theme(v: Any?): QvpTheme {
+        val m = v as? Map<*, *> ?: return QvpTheme()
+        val marks = (m["marks"] as? Map<*, *>)?.entries?.mapNotNull { (k, c) -> colorOrNull(c)?.let { (k as String) to it } }?.toMap() ?: emptyMap()
+        return QvpTheme(ink = colorOrNull(m["ink"]), diacritics = colorOrNull(m["diacritics"]), dots = colorOrNull(m["dots"]), waqf = colorOrNull(m["waqf"]), sifr = colorOrNull(m["sifr"]),
+            ayahMark = colorOrNull(m["ayahMark"]), numeral = colorOrNull(m["numeral"]), headers = colorOrNull(m["headers"]), marks = marks, transitionMs = num(m["ms"] ?: m["transitionMs"]) ?: 0)
+    }
+
+    // ── Kotlin → JS ──
+    fun word(p: QvpPage, w: QvpWord): Map<String, Any?> {
+        val forms = LinkedHashMap<String, String>()
+        for (f in Form.entries) if (f == Form.RASM_UTHMANI || p.hasForm(f)) forms[f.name.lowercase()] = p.wordForm(w.idx, f)
+        val paths = (w.firstPath until w.firstPath + w.nPaths).map { i ->
+            val kind = p.pathKind(i); val mark = p.pathMark(i); val cat = p.pathCategory(i); val fam = p.pathFamily(i)
+            mapOf("idx" to i, "kind" to kind, "kindName" to QvpEngine.kindName(kind), "mark" to mark, "markName" to QvpEngine.markName(mark), "nthMark" to p.pathNthMark(i),
+                "nthInWord" to p.pathNthInWord(i), "category" to cat, "categoryName" to QvpEngine.categoryName(cat), "family" to fam, "familyName" to QvpEngine.familyName(fam), "line" to p.pathLine(i))
+        }
+        return mapOf("idx" to w.idx, "surah" to w.surah, "ayah" to w.ayah, "word" to w.word, "line" to w.line, "lineIdx" to w.lineIdx, "ayahIdx" to w.ayahIdx,
+            "x0" to w.x0, "y0" to w.y0, "x1" to w.x1, "y1" to w.y1, "text" to w.text, "firstPath" to w.firstPath, "nPaths" to w.nPaths,
+            "wordKey" to w.wordKey, "ayahKey" to w.ayahKey, "forms" to forms, "label" to p.wordLabel(w.idx), "paths" to paths)
+    }
+    fun deco(d: QvpDecoration): Map<String, Any?> = mapOf("idx" to d.idx, "kind" to d.kind, "kindName" to listOf("ayah-ayahMark", "surah-name", "basmalah", "division-mark", "sajdah-mark").getOrElse(d.kind) { "other" },
+        "surah" to d.surah, "ayah" to d.ayah, "line" to d.line, "x0" to d.x0, "y0" to d.y0, "x1" to d.x1, "y1" to d.y1, "text" to d.text, "firstPath" to d.firstPath, "nPaths" to d.nPaths)
+    fun hit(p: QvpPage, h: QvpHitEx): Map<String, Any?> {
+        val w = if (h.word >= 0) p.words[h.word] else null
+        return mapOf("word" to h.word, "path" to h.path, "deco" to h.deco, "line" to h.line, "distance" to h.distance, "exact" to h.exact, "wordKey" to w?.wordKey, "ayahKey" to w?.ayahKey)
+    }
+    fun ayah(a: QvpAyah): Map<String, Any?> = mapOf("idx" to a.idx, "surah" to a.surah, "ayah" to a.ayah, "fragment" to a.fragment, "fragments" to a.fragments, "flags" to a.flags, "rubuAlHizb" to a.rubuAlHizb, "firstWord" to a.firstWord, "nWords" to a.nWords,
+        "ayahMarkDeco" to a.ayahMarkDeco, "bbox" to listOf(a.x0, a.y0, a.x1, a.y1))
+    fun line(l: QvpLine): Map<String, Any?> = mapOf("idx" to l.idx, "lineNo" to l.lineNo, "isHeader" to l.isHeader, "firstWord" to l.firstWord, "nWords" to l.nWords, "bbox" to listOf(l.x0, l.y0, l.x1, l.y1),
+        "bandY0" to l.bandY0, "bandY1" to l.bandY1, "centre" to l.centre)
+    fun surah(s: QvpSurah): Map<String, Any?> = mapOf("number" to s.number, "ayahCount" to s.ayahCount, "hasBanner" to s.hasBanner, "hasBasmalah" to s.hasBasmalah, "place" to s.place, "bannerDeco" to s.bannerDeco,
+        "arabic" to s.arabic, "latin" to s.latin, "english" to s.english)
+    fun division(d: QvpDivision): Map<String, Any?> = mapOf("kind" to d.kind.name.lowercase(), "n" to d.n, "surah" to d.surah, "ayah" to d.ayah, "line" to d.line, "ayahIdx" to d.ayahIdx)
+    fun ayahMark(m: QvpAyahMark): Map<String, Any?> = mapOf("deco" to m.deco, "surah" to m.surah, "ayah" to m.ayah, "line" to m.line, "cx" to m.cx, "cy" to m.cy, "r" to m.r, "ornamentPath" to m.ornamentPath, "numeralPath" to m.numeralPath)
+    fun rosette(r: QvpRosette): Map<String, Any?> = mapOf("deco" to r.deco, "surah" to r.surah, "ayah" to r.ayah, "juz" to r.juz, "hizb" to r.hizb, "nisf" to r.nisf, "rubuAlHizb" to r.rubuAlHizb, "rubuAlHizbInHizb" to r.rubuAlHizbInHizb)
+    fun sajdah(s: QvpSajdah): Map<String, Any?> = mapOf("deco" to s.deco, "surah" to s.surah, "ayah" to s.ayah, "signPath" to s.signPath)
+    fun match(m: QvpMatch): Map<String, Any?> = mapOf("word" to m.word, "index" to m.index, "loose" to m.loose, "wordKey" to m.wordKey, "text" to m.text)
+    fun cropBox(c: QvpCropBox): Map<String, Any?> = mapOf("x0" to c.x0, "y0" to c.y0, "x1" to c.x1, "y1" to c.y1, "nWords" to c.nWords, "ayahMarkDeco" to c.ayahMarkDeco)
+    fun atlasSurah(s: QvpAtlasSurah): Map<String, Any?> = mapOf("n" to s.n, "number" to s.n, "page" to s.page, "ayahCount" to s.ayahCount, "place" to s.place, "arabic" to s.arabic, "latin" to s.latin, "english" to s.english)
+    fun atlasRubuAlHizb(r: QvpAtlasRubuAlHizb): Map<String, Any?> = mapOf("rubuAlHizb" to r.rubuAlHizb, "surah" to r.surah, "ayah" to r.ayah, "page" to r.page, "ayahKey" to r.ayahKey)
+    fun layout(l: QvpLayout): Map<String, Any?> = mapOf("scale" to l.scale, "ox" to l.ox, "oy" to l.oy, "contentW" to l.contentW, "contentH" to l.contentH, "pitch" to l.pitch, "lineDy" to l.lineDy.toList(),
+        "slots" to l.slotTop.indices.map { listOf(l.slotTop[it], l.slotBottom[it]) })
+    fun pageInfo(p: QvpPage): Map<String, Any?> = mapOf("page" to p.pageNo, "width" to p.width, "height" to p.height, "nLines" to p.nLines, "nAyahs" to p.nAyahs, "nWords" to p.nWords, "nPaths" to p.nPaths, "nDecos" to p.nDecos,
+        "naturalPitch" to p.naturalPitch, "forms" to Form.entries.filter { it == Form.RASM_UTHMANI || p.hasForm(it) }.map { it.name.lowercase() })
+    fun selection(p: QvpPage): Map<String, Any?> {
+        val ws = p.selection()
+        return mapOf("words" to ws.toList(), "text" to (if (ws.isEmpty()) "" else p.text(Target.words(ws))), "citation" to (if (ws.isEmpty()) "" else p.citation(ws)),
+            "textWithCitation" to (if (ws.isEmpty()) "" else p.selectionText(Form.RASM_UTHMANI, true)))
+    }
+
+    /** Any Kotlin value (maps, lists, arrays, primitives) → a bridge value. */
+    fun toJs(v: Any?): Any? = when (v) {
+        null -> null
+        is Boolean, is String, is Int, is Double -> v
+        is Float -> v.toDouble(); is Long -> v.toDouble(); is Short -> v.toInt(); is Byte -> v.toInt()
+        is Map<*, *> -> toMap(v)
+        is Iterable<*> -> toArray(v)
+        is IntArray -> toArray(v.toList()); is FloatArray -> toArray(v.toList()); is Array<*> -> toArray(v.toList())
+        is Pair<*, *> -> toArray(listOf(v.first, v.second))
+        is Enum<*> -> v.name.lowercase()
+        else -> v.toString()
+    }
+    fun toMap(m: Map<*, *>): WritableMap {
+        val out = Arguments.createMap()
+        for ((k, v) in m) put(out, k.toString(), toJs(v))
+        return out
+    }
+    fun toArray(l: Iterable<*>): WritableArray {
+        val out = Arguments.createArray()
+        for (v in l) when (val j = toJs(v)) {
+            null -> out.pushNull(); is Boolean -> out.pushBoolean(j); is Int -> out.pushInt(j); is Double -> out.pushDouble(j); is String -> out.pushString(j)
+            is WritableMap -> out.pushMap(j); is WritableArray -> out.pushArray(j); else -> out.pushString(j.toString())
+        }
+        return out
+    }
+    private fun put(out: WritableMap, k: String, j: Any?) { when (j) {
+        null -> out.putNull(k); is Boolean -> out.putBoolean(k, j); is Int -> out.putInt(k, j); is Double -> out.putDouble(k, j); is String -> out.putString(k, j)
+        is WritableMap -> out.putMap(k, j); is WritableArray -> out.putArray(k, j); else -> out.putString(k, j.toString())
+    } }
+    fun plain(m: ReadableMap?): HashMap<String, Any?>? = m?.toHashMap()
+    fun plain(a: ReadableArray?): ArrayList<Any?>? = a?.toArrayList()
+}

package/android/src/main/java/net/quranpedia/qvp/rn/QvpModule.kt

@@ -0,0 +1,149 @@
+package net.quranpedia.qvp.rn
+
+import com.facebook.react.bridge.*
+import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.UIManagerHelper
+import net.quranpedia.qvp.*
+import net.quranpedia.qvp.Target
+
+/**
+ * Promise-based queries on the page behind a `<QvpPageView />` (looked up by react tag) plus engine-wide
+ * helpers and the atlas. Everything runs on the UI thread, where the view draws, so the engine is never
+ * touched from two threads. Names follow docs/API.md.
+ */
+@ReactModule(name = QvpModule.NAME)
+class QvpModule(private val ctx: ReactApplicationContext) : ReactContextBaseJavaModule(ctx) {
+    override fun getName() = NAME
+    private val atlases = HashMap<Int, QvpAtlas>()
+    private val atlasByUri = HashMap<String, Int>()
+    private var nextAtlas = 1
+
+    private fun view(tag: Int): QvpRnPageView? = QvpRegistry.get(tag) ?: runCatching { UIManagerHelper.getUIManagerForReactTag(ctx, tag)?.resolveView(tag) as? QvpRnPageView }.getOrNull()
+    // Every @ReactMethod must be `void` for the TurboModule interop layer: these helpers return Unit on purpose.
+    private fun ui(promise: Promise, block: () -> Any?) {
+        UiThreadUtil.runOnUiThread {
+            try { promise.resolve(Marshal.toJs(block())) } catch (e: Throwable) { promise.reject("qvp", e.message ?: e.toString(), e) }
+        }
+    }
+    private fun withPage(tag: Int, promise: Promise, block: (QvpRnPageView, QvpPage) -> Any?) {
+        ui(promise) {
+            val v = view(tag) ?: throw IllegalStateException("no QvpPageView with tag $tag")
+            val p = v.page ?: throw IllegalStateException("QvpPageView $tag has no page loaded")
+            block(v, p)
+        }
+    }
+    private fun withAtlas(id: Int, promise: Promise, block: (QvpAtlas) -> Any?) { ui(promise) { block(atlases[id] ?: throw IllegalStateException("no atlas $id")) } }
+    private fun opt(m: ReadableMap?): Map<String, Any?> = m?.toHashMap() ?: emptyMap()
+    private fun tgt(d: Dynamic, p: QvpPage): Target = Marshal.target(when (d.type) {
+        ReadableType.String -> d.asString(); ReadableType.Number -> d.asDouble(); ReadableType.Array -> d.asArray()?.toArrayList(); ReadableType.Map -> d.asMap()?.toHashMap(); else -> null }, p)
+    private fun ints(a: ReadableArray?): IntArray = a?.toArrayList()?.mapNotNull { (it as? Number)?.toInt() }?.toIntArray() ?: IntArray(0)
+
+    // ── page facts ──
+    @ReactMethod fun info(tag: Int, promise: Promise) = withPage(tag, promise) { v, p -> Marshal.pageInfo(p) + mapOf("loadMs" to v.loadMs, "bytes" to v.pageBytes) }
+    @ReactMethod fun words(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.words.map { Marshal.word(p, it) } }
+    @ReactMethod fun word(tag: Int, idx: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.words.getOrNull(idx)?.let { Marshal.word(p, it) } }
+    @ReactMethod fun ayahs(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.ayahs.map { Marshal.ayah(it) } }
+    @ReactMethod fun lines(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.lines.map { Marshal.line(it) } }
+    @ReactMethod fun decos(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.decos.map { Marshal.deco(it) } }
+    @ReactMethod fun findWord(tag: Int, s: Int, a: Int, w: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.findWord(s, a, w) }
+    @ReactMethod fun resolve(tag: Int, target: Dynamic, promise: Promise) = withPage(tag, promise) { _, p -> p.resolve(tgt(target, p)).toList() }
+    @ReactMethod fun wordForm(tag: Int, idx: Int, form: String?, promise: Promise) = withPage(tag, promise) { _, p -> p.wordForm(idx, Marshal.form(form)) }
+    @ReactMethod fun hasForm(tag: Int, form: String?, promise: Promise) = withPage(tag, promise) { _, p -> p.hasForm(Marshal.form(form)) }
+    @ReactMethod fun attachWords(tag: Int, json: String, promise: Promise) = withPage(tag, promise) { _, p -> p.attachWords(json) }
+
+    // ── metadata ──
+    @ReactMethod fun surahs(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.surahs().map { Marshal.surah(it) } }
+    @ReactMethod fun divisions(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.divisions().map { Marshal.division(it) } }
+    @ReactMethod fun ayahMarks(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.ayahMarks().map { Marshal.ayahMark(it) } }
+    @ReactMethod fun rosettes(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.rosettes().map { Marshal.rosette(it) } }
+    @ReactMethod fun sajdahs(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.sajdahs().map { Marshal.sajdah(it) } }
+    @ReactMethod fun ayahKeys(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.ayahKeys().map { mapOf("surah" to it.first, "ayah" to it.second, "ayahKey" to "${it.first}:${it.second}") } }
+    @ReactMethod fun ayahWordCount(tag: Int, s: Int, a: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.ayahWordCount(s, a).let { mapOf("count" to it.first, "complete" to it.second) } }
+    @ReactMethod fun reciteMap(tag: Int, s: Int, a: Int, n: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.reciteMap(s, a, n)?.toList() }
+    @ReactMethod fun wordLabel(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.wordLabel(i) }
+    @ReactMethod fun ayahLabel(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.ayahLabel(i) }
+
+    // ── text & search ──
+    @ReactMethod fun text(tag: Int, target: Dynamic, opts: ReadableMap?, promise: Promise) = withPage(tag, promise) { _, p ->
+        val o = opt(opts); p.text(tgt(target, p), Marshal.form(o["form"]), (o["wordSep"] as? String) ?: " ", (o["lineSep"] as? String) ?: "\n") }
+    @ReactMethod fun search(tag: Int, query: String, opts: ReadableMap?, promise: Promise) = withPage(tag, promise) { _, p ->
+        val o = opt(opts)
+        p.search(query, Marshal.form(o["form"], Form.SEARCH), Marshal.searchMode(o["mode"]), o["normalize"] != false, o["loose"] != false, (o["limit"] as? Number)?.toInt() ?: 0).map { Marshal.match(it) } }
+    @ReactMethod fun citation(tag: Int, words: ReadableArray, promise: Promise) = withPage(tag, promise) { _, p -> p.citation(ints(words)) }
+    @ReactMethod fun arabic(kind: String, s: String, promise: Promise) = ui(promise) { when (kind) { "strip" -> QvpEngine.strip(s); "fold" -> QvpEngine.fold(s); "normalize" -> QvpEngine.normalize(s); "loose", "looseKey" -> QvpEngine.looseKey(s); else -> s } }
+
+    // ── hit testing / layout (the view already does gestures; these are for scroll-into-view etc.) ──
+    @ReactMethod fun hitTestViewEx(tag: Int, x: Double, y: Double, opts: ReadableMap?, promise: Promise) = withPage(tag, promise) { v, p ->
+        val o = opt(opts); val d = v.resources.displayMetrics.density
+        p.hitTestViewEx(((x * d).toFloat() - v.inner.viewOx) / v.inner.viewScale, ((y * d).toFloat() - v.inner.viewOy) / v.inner.viewScale, QvpHitOptions((o["maxDistance"] as? Number)?.toFloat() ?: 6f, (o["gapBias"] as? Number)?.toFloat() ?: 0.6f, o["exactFirst"] != false))?.let { Marshal.hit(p, it) } }
+    @ReactMethod fun wordBoxView(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { v, p -> val d = v.resources.displayMetrics.density
+        p.wordBoxView(i)?.let { b -> mapOf("x0" to (v.inner.viewOx + b[0] * v.inner.viewScale) / d, "y0" to (v.inner.viewOy + b[1] * v.inner.viewScale) / d, "x1" to (v.inner.viewOx + b[2] * v.inner.viewScale) / d, "y1" to (v.inner.viewOy + b[3] * v.inner.viewScale) / d) } }
+    @ReactMethod fun currentLayout(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.currentLayout?.let { Marshal.layout(it) } }
+    @ReactMethod fun relayout(tag: Int, promise: Promise) = withPage(tag, promise) { v, _ -> v.inner.relayout(); v.resetView(); null }
+    @ReactMethod fun resetView(tag: Int, promise: Promise) = withPage(tag, promise) { v, _ -> v.resetView(); null }
+    @ReactMethod fun gapToFill(pw: Double, ph: Double, lines: Int, vw: Double, vh: Double, max: Double, promise: Promise) = ui(promise) { QvpEngine.gapToFill(pw.toFloat(), ph.toFloat(), lines, vw.toFloat(), vh.toFloat(), max.toFloat()) }
+    @ReactMethod fun wastedFraction(pw: Double, ph: Double, vw: Double, vh: Double, promise: Promise) = ui(promise) { QvpEngine.wastedFraction(pw.toFloat(), ph.toFloat(), vw.toFloat(), vh.toFloat()) }
+    @ReactMethod fun stats(tag: Int, promise: Promise) = ui(promise) { view(tag)?.stats() }
+    @ReactMethod fun invalidate(tag: Int, promise: Promise) = ui(promise) { view(tag)?.inner?.invalidate(); null }
+
+    // ── selection ──
+    @ReactMethod fun select(tag: Int, anchor: Int, focus: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.select(anchor, focus); v.inner.invalidate(); Marshal.selection(p) }
+    @ReactMethod fun clearSelection(tag: Int, promise: Promise) = withPage(tag, promise) { v, _ -> v.inner.clearSelection(); null }
+    @ReactMethod fun selection(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> Marshal.selection(p) }
+    @ReactMethod fun selectionText(tag: Int, form: String?, citation: Boolean, promise: Promise) = withPage(tag, promise) { _, p -> p.selectionText(Marshal.form(form), citation) }
+
+    // ── memorisation (stepwise ops; `mask` / `reveal` props hold the declarative part) ──
+    @ReactMethod fun revealNext(tag: Int, n: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.revealNext(n).also { v.inner.invalidate() } }
+    @ReactMethod fun hideBack(tag: Int, n: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.hideBack(n).also { v.inner.invalidate() } }
+    @ReactMethod fun revealWord(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.revealWord(i).also { v.inner.invalidate() } }
+    @ReactMethod fun hideWord(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.hideWord(i).also { v.inner.invalidate() } }
+    @ReactMethod fun revealAll(tag: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.revealAll(); v.inner.invalidate(); null }
+    @ReactMethod fun hideAll(tag: Int, promise: Promise) = withPage(tag, promise) { v, p -> p.hideAll(); v.inner.invalidate(); null }
+    @ReactMethod fun maskHidden(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.maskHidden().toList() }
+    @ReactMethod fun maskWords(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.maskWords().toList() }
+    @ReactMethod fun revealSteps(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.revealSteps() }
+    @ReactMethod fun revealAt(tag: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.revealAt()?.toDouble() }
+    @ReactMethod fun revealStepOf(tag: Int, i: Int, promise: Promise) = withPage(tag, promise) { _, p -> p.revealStepOf(i).toDouble() }
+
+    // ── crop ──
+    @ReactMethod fun cropBox(tag: Int, target: Dynamic, opts: ReadableMap?, promise: Promise) = withPage(tag, promise) { _, p ->
+        val o = opt(opts); p.cropBox(tgt(target, p), (o["pad"] as? Number)?.toFloat() ?: 2f, o["keepAyahMarks"] != false)?.let { Marshal.cropBox(it) } }
+    @ReactMethod fun cropSvg(tag: Int, target: Dynamic, opts: ReadableMap?, promise: Promise) = withPage(tag, promise) { _, p ->
+        val o = opt(opts); p.cropSvg(tgt(target, p), (o["pad"] as? Number)?.toFloat() ?: 2f, o["keepAyahMarks"] != false, Marshal.color(o["background"], 0)) }
+
+    // ── atlas ──
+    @ReactMethod fun loadAtlas(uri: String, promise: Promise) = ui(promise) {
+        atlasByUri[uri] ?: run {
+            val bytes = when {
+                uri.startsWith("asset://") -> ctx.assets.open(uri.removePrefix("asset://")).use { it.readBytes() }
+                uri.startsWith("asset:") -> ctx.assets.open(uri.removePrefix("asset:")).use { it.readBytes() }
+                uri.startsWith("file://") -> java.io.File(uri.removePrefix("file://")).readBytes()
+                uri.startsWith("/") -> java.io.File(uri).readBytes()
+                uri.startsWith("base64:") -> android.util.Base64.decode(uri.removePrefix("base64:"), android.util.Base64.DEFAULT)
+                else -> ctx.assets.open(uri).use { it.readBytes() }
+            }
+            val id = nextAtlas++; atlases[id] = QvpAtlas(bytes); atlasByUri[uri] = id; id
+        }
+    }
+    @ReactMethod fun freeAtlas(id: Int, promise: Promise) = ui(promise) { atlases.remove(id)?.close(); atlasByUri.entries.removeAll { it.value == id }; null }
+    @ReactMethod fun atlasPageOf(id: Int, s: Int, a: Int, promise: Promise) = withAtlas(id, promise) { it.pageOf(s, a) }
+    @ReactMethod fun atlasPageRange(id: Int, page: Int, promise: Promise) = withAtlas(id, promise) { it.pageRange(page)?.let { r -> mapOf("first" to mapOf("surah" to r.first.first, "ayah" to r.first.second), "last" to mapOf("surah" to r.second.first, "ayah" to r.second.second)) } }
+    @ReactMethod fun atlasPages(id: Int, promise: Promise) = withAtlas(id, promise) { it.pages() }
+    @ReactMethod fun atlasSurah(id: Int, n: Int, promise: Promise) = withAtlas(id, promise) { it.surah(n)?.let { s -> Marshal.atlasSurah(s) } }
+    @ReactMethod fun atlasSurahs(id: Int, promise: Promise) = withAtlas(id, promise) { it.surahs().map { s -> Marshal.atlasSurah(s) } }
+    @ReactMethod fun atlasPageOfSurah(id: Int, n: Int, promise: Promise) = withAtlas(id, promise) { it.pageOfSurah(n) }
+    @ReactMethod fun atlasDivision(id: Int, kind: String, n: Int, promise: Promise) = withAtlas(id, promise) { it.division(Marshal.division(kind), n)?.let { r -> Marshal.atlasRubuAlHizb(r) } }
+    @ReactMethod fun atlasDivisionAt(id: Int, kind: String, s: Int, a: Int, promise: Promise) = withAtlas(id, promise) { it.divisionAt(Marshal.division(kind), s, a) }
+    @ReactMethod fun atlasJuzAt(id: Int, s: Int, a: Int, promise: Promise) = withAtlas(id, promise) { it.juzAt(s, a) }
+    @ReactMethod fun atlasPagesOfJuz(id: Int, n: Int, promise: Promise) = withAtlas(id, promise) { it.pagesOfJuz(n)?.let { r -> listOf(r.first, r.second) } }
+    @ReactMethod fun atlasFindSurah(id: Int, text: String, promise: Promise) = withAtlas(id, promise) { it.findSurah(text).map { s -> Marshal.atlasSurah(s) } }
+
+    // ── names ──
+    @ReactMethod fun markName(m: Int, promise: Promise) = ui(promise) { QvpEngine.markName(m) }
+    @ReactMethod fun markFromName(s: String, promise: Promise) = ui(promise) { QvpEngine.markFromName(s) }
+    override fun getConstants(): Map<String, Any> = mapOf("version" to QvpEngine.version(), "marks" to QVP_MARKS,
+        "kinds" to (0..4).map { QvpEngine.kindName(it) }, "families" to (0..7).map { QvpEngine.familyName(it) }, "categories" to (0..8).map { QvpEngine.categoryName(it) })
+
+    override fun invalidate() { atlases.values.forEach { it.close() }; atlases.clear(); atlasByUri.clear(); super.invalidate() }
+    companion object { const val NAME = "QvpModule" }
+}

package/android/src/main/java/net/quranpedia/qvp/rn/QvpPackage.kt

@@ -0,0 +1,11 @@
+package net.quranpedia.qvp.rn
+
+import com.facebook.react.ReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.uimanager.ViewManager
+
+class QvpPackage : ReactPackage {
+    override fun createNativeModules(ctx: ReactApplicationContext): List<NativeModule> = listOf(QvpModule(ctx))
+    override fun createViewManagers(ctx: ReactApplicationContext): List<ViewManager<*, *>> = listOf(QvpPageViewManager())
+}

package/android/src/main/java/net/quranpedia/qvp/rn/QvpPageViewManager.kt

@@ -0,0 +1,48 @@
+package net.quranpedia.qvp.rn
+
+import com.facebook.react.bridge.ReadableArray
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.uimanager.SimpleViewManager
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.annotations.ReactProp
+import net.quranpedia.qvp.QvpColor
+
+/** `<QvpPageView />`: props are marshalled onto [QvpRnPageView]; [onAfterUpdateTransaction] commits them in one pass. */
+class QvpPageViewManager : SimpleViewManager<QvpRnPageView>() {
+    override fun getName() = NAME
+    override fun createViewInstance(c: ThemedReactContext) = QvpRnPageView(c)
+    override fun onDropViewInstance(view: QvpRnPageView) { view.destroy(); super.onDropViewInstance(view) }
+    override fun onAfterUpdateTransaction(view: QvpRnPageView) { super.onAfterUpdateTransaction(view); view.commit() }
+
+    override fun getExportedCustomDirectEventTypeConstants(): MutableMap<String, Any> {
+        val m = HashMap<String, Any>()
+        for (e in EVENTS) m[e] = mapOf("registrationName" to e)
+        return m
+    }
+
+    @ReactProp(name = "pageUri") fun setPageUri(v: QvpRnPageView, s: String?) { v.pageUri = s }
+    @ReactProp(name = "pageBase64") fun setPageBase64(v: QvpRnPageView, s: String?) { v.pageBase64 = s }
+    @ReactProp(name = "wordsUri") fun setWordsUri(v: QvpRnPageView, s: String?) { v.wordsUri = s }
+    @ReactProp(name = "padTop", defaultFloat = 0f) fun setPadTop(v: QvpRnPageView, f: Float) = v.setPadTopDp(f)
+    @ReactProp(name = "padBottom", defaultFloat = 0f) fun setPadBottom(v: QvpRnPageView, f: Float) = v.setPadBottomDp(f)
+    @ReactProp(name = "padSide", defaultFloat = 0f) fun setPadSide(v: QvpRnPageView, f: Float) = v.setPadSideDp(f)
+    @ReactProp(name = "lineSpacing", defaultFloat = 1f) fun setLineSpacing(v: QvpRnPageView, f: Float) = v.setLineSpacingProp(f)
+    @ReactProp(name = "lineGap", defaultFloat = 0f) fun setLineGap(v: QvpRnPageView, f: Float) = v.setLineGapProp(f)
+    @ReactProp(name = "fillHeight", defaultBoolean = false) fun setFillHeight(v: QvpRnPageView, b: Boolean) = v.setFillHeightProp(b)
+    @ReactProp(name = "paperColor") fun setPaperColor(v: QvpRnPageView, s: String?) { v.paperColor = if (s.isNullOrBlank()) 0 else QvpColor.argb(QvpColor.parse(s)); v.invalidate() }
+    @ReactProp(name = "defaultInk") fun setDefaultInk(v: QvpRnPageView, s: String?) { v.defaultInkProp = s }
+    @ReactProp(name = "selectionBand") fun setSelectionBand(v: QvpRnPageView, s: String?) { if (!s.isNullOrBlank()) v.selectionBand = QvpColor.parse(s) }
+    @ReactProp(name = "selectionEnabled", defaultBoolean = true) fun setSelectionEnabled(v: QvpRnPageView, b: Boolean) { v.selectionEnabled = b }
+    @ReactProp(name = "zoomEnabled", defaultBoolean = true) fun setZoomEnabled(v: QvpRnPageView, b: Boolean) { v.zoomEnabled = b }
+    @ReactProp(name = "hitMaxDistance", defaultFloat = 6f) fun setHitMaxDistance(v: QvpRnPageView, f: Float) { v.hitOptions = v.hitOptions.copy(maxDistance = f) }
+    @ReactProp(name = "theme") fun setTheme(v: QvpRnPageView, m: ReadableMap?) { v.themeProp = Marshal.plain(m) }
+    @ReactProp(name = "styles") fun setStyles(v: QvpRnPageView, a: ReadableArray?) { v.stylesProp = Marshal.plain(a) }
+    @ReactProp(name = "highlights") fun setHighlights(v: QvpRnPageView, a: ReadableArray?) { v.highlightsProp = Marshal.plain(a) }
+    @ReactProp(name = "mask") fun setMask(v: QvpRnPageView, m: ReadableMap?) { v.maskProp = Marshal.plain(m) }
+    @ReactProp(name = "reveal") fun setReveal(v: QvpRnPageView, m: ReadableMap?) { v.revealProp = Marshal.plain(m) }
+
+    companion object {
+        const val NAME = "QvpPageView"
+        val EVENTS = listOf("onWordTap", "onDecoTap", "onEmptyTap", "onSelectionChanged", "onPageLoad", "onRevealChanged", "onError")
+    }
+}

package/android/src/main/java/net/quranpedia/qvp/rn/QvpRnPageView.kt

@@ -0,0 +1,235 @@
+package net.quranpedia.qvp.rn
+
+import android.util.Base64
+import android.util.Log
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.UIManagerHelper
+import com.facebook.react.uimanager.events.Event
+import android.widget.FrameLayout
+import net.quranpedia.qvp.*
+import net.quranpedia.qvp.Target
+import java.io.File
+
+/**
+ * The React Native host of [QvpPageView]. It owns the loaded [QvpPage], loads bytes from the prop-given
+ * URI, and reconciles the declarative props (theme / styles / highlights / mask / reveal) against engine
+ * handles so JS never sees a handle. Every decision (hit-test, layout, style resolution, bands, masks)
+ * is the engine's; this class only marshals and forwards.
+ */
+class QvpRnPageView(private val ctx: ThemedReactContext) : FrameLayout(ctx) {
+    private val density = ctx.resources.displayMetrics.density
+    /** The Kotlin library's renderer (final class, so hosted rather than subclassed). */
+    val inner = QvpPageView(ctx).also { addView(it, LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)) }
+    var page: QvpPage?
+        get() = inner.page
+        set(v) { inner.page = v }
+    var paperColor: Int get() = inner.paperColor; set(v) { inner.paperColor = v; inner.invalidate() }
+    var selectionBand: Int get() = inner.selectionBand; set(v) { inner.selectionBand = v }
+    var selectionEnabled: Boolean get() = inner.selectionEnabled; set(v) { inner.selectionEnabled = v }
+    var zoomEnabled: Boolean get() = inner.zoomEnabled; set(v) { inner.zoomEnabled = v }
+    var hitOptions: QvpHitOptions get() = inner.hitOptions; set(v) { inner.hitOptions = v }
+
+    /** React Native sizes this host directly (no measure pass), so size the child by hand. */
+    override fun onLayout(changed: Boolean, l: Int, t: Int, r: Int, b: Int) {
+        val w = r - l; val h = b - t
+        inner.measure(MeasureSpec.makeMeasureSpec(w, MeasureSpec.EXACTLY), MeasureSpec.makeMeasureSpec(h, MeasureSpec.EXACTLY))
+        inner.layout(0, 0, w, h)
+        centre()
+    }
+    /** Fit + centre: the library's resetView fits by height and pins the pan at x = 0; centre the pan horizontally (pan is host state). */
+    fun resetView() { inner.resetView(); centre() }
+    private fun centre() {
+        val l = page?.currentLayout ?: return
+        inner.viewOx = ((inner.width - l.contentW * inner.viewScale) / 2f).coerceAtLeast(0f); inner.invalidate()
+    }
+
+    // ── desired props (set by the manager) ──
+    var pageUri: String? = null
+    var pageBase64: String? = null
+    var wordsUri: String? = null
+    var defaultInkProp: String? = null
+    var themeProp: Map<String, Any?>? = null
+    var stylesProp: List<Any?>? = null
+    var highlightsProp: List<Any?>? = null
+    var maskProp: Map<String, Any?>? = null
+    var revealProp: Map<String, Any?>? = null
+    var layoutDirty = true
+
+    // ── applied state ──
+    private var loadedKey: String? = null
+    private var appliedTheme: Map<String, Any?>? = null
+    private var themeHandle = 0
+    private class Rule(val handle: Int, val entry: Map<*, *>)
+    private val styleHandles = LinkedHashMap<String, Rule>()
+    private val highlightHandles = LinkedHashMap<String, Rule>()
+    private var appliedMask: Map<String, Any?>? = null
+    private var appliedReveal: Map<String, Any?>? = null   // without "at"
+    private var appliedRevealAt: Long? = null
+    private var appliedInk: Int? = null
+    var revealSteps = 0; private set
+    var loadMs = 0.0; private set
+    var pageBytes = 0; private set
+
+    init {
+        inner.onWordTap = { w, h -> page?.let { p -> emit("onWordTap", mapOf("word" to Marshal.word(p, w), "hit" to Marshal.hit(p, h))) } }
+        inner.onDecoTap = { d, h -> page?.let { p -> emit("onDecoTap", mapOf("deco" to Marshal.deco(d), "hit" to Marshal.hit(p, h))) } }
+        inner.onEmptyTap = { emit("onEmptyTap", emptyMap()) }
+        inner.onSelectionChanged = { page?.let { p -> emit("onSelectionChanged", Marshal.selection(p)) } }
+    }
+
+    override fun onAttachedToWindow() { super.onAttachedToWindow(); QvpRegistry.register(this) }
+    override fun onDetachedFromWindow() { QvpRegistry.unregister(this); super.onDetachedFromWindow() }
+
+    fun destroy() { QvpRegistry.unregister(this); page?.close(); page = null; loadedKey = null }
+
+    /** Padding props arrive in dp. */
+    fun setPadTopDp(v: Float) { inner.padTop = v * density; layoutDirty = true }
+    fun setPadBottomDp(v: Float) { inner.padBottom = v * density; layoutDirty = true }
+    fun setPadSideDp(v: Float) { inner.padSide = v * density; layoutDirty = true }
+    fun setLineSpacingProp(v: Float) { inner.lineSpacing = v; layoutDirty = true }
+    fun setLineGapProp(v: Float) { inner.lineGap = v; layoutDirty = true }
+    fun setFillHeightProp(v: Boolean) { inner.fillHeight = v; layoutDirty = true }
+
+    // ── bytes ──
+    private fun readUri(uri: String): ByteArray {
+        val u = uri.trim()
+        return when {
+            u.startsWith("asset://") -> ctx.assets.open(u.removePrefix("asset://")).use { it.readBytes() }
+            u.startsWith("asset:") -> ctx.assets.open(u.removePrefix("asset:")).use { it.readBytes() }
+            u.startsWith("file://") -> File(u.removePrefix("file://")).readBytes()
+            u.startsWith("/") -> File(u).readBytes()
+            u.startsWith("base64:") -> Base64.decode(u.removePrefix("base64:"), Base64.DEFAULT)
+            else -> ctx.assets.open(u).use { it.readBytes() }
+        }
+    }
+
+    /** Called by the manager after every prop batch. */
+    fun commit() {
+        try {
+            ensurePage()
+            val p = page
+            if (p != null) {
+                applyInk(p); applyTheme(p); applyStyles(p); applyHighlights(p); applyMask(p); applyReveal(p)
+            }
+            if (layoutDirty) { layoutDirty = false; inner.relayout(); resetView() }
+            inner.invalidate()
+        } catch (e: Exception) {
+            Log.e("QvpRn", "commit failed", e)
+            emit("onError", mapOf("message" to (e.message ?: e.toString())))
+        }
+    }
+
+    private fun ensurePage() {
+        val key = pageBase64?.let { "b64:" + it.hashCode() } ?: pageUri
+        if (key == loadedKey) return
+        // drop everything bound to the old page: handles die with it
+        themeHandle = 0; appliedTheme = null; styleHandles.clear(); highlightHandles.clear(); appliedMask = null; appliedReveal = null; appliedRevealAt = null; appliedInk = null; revealSteps = 0
+        page?.close(); page = null; loadedKey = key
+        if (key == null) return
+        val bytes = pageBase64?.let { Base64.decode(it, Base64.DEFAULT) } ?: readUri(pageUri!!)
+        val t0 = System.nanoTime()
+        val p = QvpPage(bytes); p.buildPaths()
+        loadMs = (System.nanoTime() - t0) / 1e6; pageBytes = bytes.size
+        wordsUri?.let { runCatching { p.attachWords(readUri(it)) }.onFailure { e -> Log.w("QvpRn", "words sidecar: $e") } }
+        page = p; layoutDirty = true
+        emit("onPageLoad", Marshal.pageInfo(p) + mapOf("loadMs" to loadMs, "bytes" to pageBytes, "uri" to pageUri))
+    }
+
+    private fun applyInk(p: QvpPage) {
+        val ink = Marshal.color(defaultInkProp, 0x231f20ff.toInt())
+        if (appliedInk != ink) { appliedInk = ink; p.setDefaultInk(ink) }
+    }
+    private fun applyTheme(p: QvpPage) {
+        if (themeProp == appliedTheme) return
+        if (themeHandle != 0) { p.unstyle(themeHandle); themeHandle = 0 }
+        appliedTheme = themeProp
+        themeProp?.let { themeHandle = p.theme(Marshal.theme(it)) }
+    }
+    private fun entries(list: List<Any?>?): LinkedHashMap<String, Map<*, *>> {
+        val out = LinkedHashMap<String, Map<*, *>>()
+        list?.forEach { e -> (e as? Map<*, *>)?.let { m -> (m["id"]?.toString())?.let { out[it] = m } } }
+        return out
+    }
+    private fun applyStyles(p: QvpPage) {
+        val want = entries(stylesProp)
+        for (id in styleHandles.keys.toList()) if (!want.containsKey(id)) { p.unstyle(styleHandles.remove(id)!!.handle) }
+        for ((id, e) in want) {
+            val old = styleHandles[id]
+            if (old != null && old.entry == e) continue
+            val sameShape = old != null && old.entry["selector"] == e["selector"] && old.entry["target"] == e["target"] && old.entry["layer"] == e["layer"] && old.entry["hide"] == e["hide"] && e["hide"] != true
+            if (sameShape) { p.restyle(old!!.handle, Marshal.color(e["color"], 0), (e["ms"] as? Number)?.toInt() ?: 0); styleHandles[id] = Rule(old.handle, e); continue }
+            if (old != null) p.unstyle(old.handle)
+            val ms = (e["ms"] as? Number)?.toInt() ?: 0
+            val layer = (e["layer"] as? Number)?.toInt() ?: QvpLayer.BASE
+            val color = Marshal.color(e["color"], 0)
+            val h = when {
+                e["hide"] == true -> Marshal.selector(e["selector"])?.let { p.hide(it) } ?: 0
+                e["selector"] != null -> Marshal.selector(e["selector"])?.let { p.style(it, color, ms, layer) } ?: 0
+                e["target"] != null -> p.styleTarget(Marshal.target(e["target"], p), color, ms, layer)
+                else -> 0
+            }
+            if (h != 0) styleHandles[id] = Rule(h, e) else styleHandles.remove(id)
+        }
+    }
+    private fun applyHighlights(p: QvpPage) {
+        val want = entries(highlightsProp)
+        for (id in highlightHandles.keys.toList()) if (!want.containsKey(id)) { p.unhighlight(highlightHandles.remove(id)!!.handle) }
+        for ((id, e) in want) {
+            val old = highlightHandles[id]
+            if (old != null && old.entry == e) continue
+            val style = Marshal.highlightStyle(e["style"])
+            if (old == null) { val h = p.highlight(Marshal.target(e["target"], p), style); if (h != 0) highlightHandles[id] = Rule(h, e); continue }
+            if (old.entry["style"] != e["style"]) p.restyleHighlight(old.handle, style)
+            if (old.entry["target"] != e["target"]) p.rehighlight(old.handle, Marshal.target(e["target"], p))
+            highlightHandles[id] = Rule(old.handle, e)
+        }
+    }
+    private fun applyMask(p: QvpPage) {
+        if (maskProp == appliedMask) return
+        appliedMask = maskProp
+        p.unmask()
+        val m = maskProp ?: return
+        val paper = Marshal.color(m["blockColor"], 0xd9d4c8ff.toInt())
+        p.maskOptions(paper, (m["padX"] as? Number)?.toFloat() ?: 0.6f, (m["padY"] as? Number)?.toFloat() ?: 0.6f, (m["radius"] as? Number)?.toFloat() ?: 0.8f, m["reverse"] == true)
+        p.mask(Marshal.target(m["target"], p), Marshal.maskMode(m["mode"]))
+    }
+    private fun applyReveal(p: QvpPage) {
+        val r = revealProp
+        val cfg = r?.filterKeys { it != "at" }
+        if (cfg != appliedReveal) {
+            appliedReveal = cfg; appliedRevealAt = null
+            if (cfg == null) { p.revealStop(); revealSteps = 0; emit("onRevealChanged", mapOf("steps" to 0, "at" to null)); return }
+            revealSteps = p.revealStart((cfg["lit"] as? Number)?.toInt() ?: 1, cfg["byAyah"] == true, Marshal.color(cfg["grey"], 0xc9c4b8ff.toInt()), Marshal.color(cfg["ink"], appliedInk ?: 0x231f20ff.toInt()),
+                cfg["ayahMarks"] != false, (cfg["ms"] as? Number)?.toInt() ?: 0)
+            emit("onRevealChanged", mapOf("steps" to revealSteps, "at" to -1))
+        }
+        if (r == null) return
+        val at = (r["at"] as? Number)?.toLong() ?: -1L
+        if (at != appliedRevealAt) { appliedRevealAt = at; p.revealGoto(at) }
+    }
+
+    // ── events ──
+    private class QvpEvent(surfaceId: Int, viewTag: Int, private val name: String, private val payload: WritableMap) : Event<QvpEvent>(surfaceId, viewTag) {
+        override fun getEventName() = name
+        override fun getEventData(): WritableMap = payload
+    }
+    fun emit(name: String, payload: Map<String, Any?>) {
+        if (id <= 0) return
+        val dispatcher = UIManagerHelper.getEventDispatcherForReactTag(ctx, id) ?: return
+        dispatcher.dispatchEvent(QvpEvent(UIManagerHelper.getSurfaceId(this), id, name, Marshal.toMap(payload)))
+    }
+
+    fun stats(): Map<String, Any?> = mapOf("loadMs" to loadMs, "bytes" to pageBytes, "baseMs" to inner.lastBaseMs, "overlayMs" to inner.lastOverlayMs, "basePaths" to inner.lastBasePaths, "overlayPaths" to inner.lastOverlayPaths,
+        "bands" to inner.lastBands, "hitUs" to inner.lastHitUs, "animating" to inner.animating, "styleHandles" to (page?.styleHandles()?.size ?: 0), "highlightHandles" to (page?.highlightHandles()?.size ?: 0),
+        "engineVersion" to QvpEngine.version(), "viewScale" to inner.viewScale, "layout" to page?.currentLayout?.let { Marshal.layout(it) })
+}
+
+/** Views by react tag, so the module can find the page behind a `viewTag` without going through the UIManager. */
+object QvpRegistry {
+    private val views = HashMap<Int, QvpRnPageView>()
+    fun register(v: QvpRnPageView) { if (v.id > 0) views[v.id] = v }
+    fun unregister(v: QvpRnPageView) { views.entries.removeAll { it.value === v } }
+    fun get(tag: Int): QvpRnPageView? = views[tag]
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@quran.ws/qvp-react-native",
+  "version": "0.1.0",
+  "description": "React Native wrapper for the QVP vector mushaf engine (Android; iOS TODO). Thin marshalling over the Kotlin library, which is JNI over qvp.h.",
+  "main": "src/index.tsx",
+  "types": "src/index.tsx",
+  "react-native": "src/index.tsx",
+  "source": "src/index.tsx",
+  "files": [
+    "src",
+    "android/build.gradle",
+    "android/src",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "keywords": [
+    "react-native",
+    "quran",
+    "mushaf",
+    "qvp",
+    "vector"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quran-ws/quran-engine.git",
+    "directory": "packages/react-native/qvp-react-native"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "react": "19.2.3",
+    "react-native": "0.87.1",
+    "typescript": "^5.8.0"
+  }
+}

package/src/index.tsx

@@ -0,0 +1,346 @@
+/**
+ * @quran.ws/qvp-react-native — typed JS API over the native module.
+ *
+ * Names follow docs/API.md. Nothing here decides anything: targets, selectors and colours are marshalled
+ * to the Kotlin library (`net.quranpedia.qvp`), which is JNI over crates/qvp-ffi/include/qvp.h.
+ * Declarative props (`highlights`, `styles`, `theme`, `mask`, `reveal`) are reconciled against engine
+ * handles on the native side, so JS never sees a handle.
+ */
+import React, { forwardRef, useImperativeHandle, useMemo, useRef } from 'react';
+import {
+  findNodeHandle,
+  NativeModules,
+  requireNativeComponent,
+  type HostComponent,
+  type NativeSyntheticEvent,
+  type ViewProps,
+} from 'react-native';
+
+// ── constants (mirror qvp.h) ─────────────────────────────────────────────────────────────────
+export const KIND = { BODY: 0, MARK: 1, AYAH_NUMBER: 2, AYAH_MARK_ORNAMENT: 3, HEADER_INK: 4, OTHER: 255 } as const;
+export const FAMILY = { NONE: 0, DIACRITIC: 1, TANWIN: 2, DOTS: 3, WAQF: 4, SIFR: 5, SAJDAH: 6, READING_SIGN: 7 } as const;
+export const CATEGORY = { NONE: 0, HARAKAH: 1, TANWIN: 2, LETTER_DOT: 3, ORTHOGRAPHIC: 4, DABT: 5, WAQF: 6, READING_SIGN: 7, STANDALONE: 8 } as const;
+export const DECO = { AYAH_MARK: 0, SURAH_NAME: 1, BASMALAH: 2, DIVISION_MARK: 3, SAJDAH_MARK: 4 } as const;
+export const LAYER = { BASE: 0, THEME: 10, HIGHLIGHT: 50, SELECTION: 60, TOP: 100 } as const;
+export const DIVISION = { JUZ: 0, HIZB: 1, NISF: 2, RUBU_AL_HIZB: 3 } as const;
+export const MARKS = ['', 'fathah', 'kasrah', 'dammah', 'tanwin_al_fath', 'tanwin_al_kasr', 'tanwin_al_damm', 'shaddah', 'sukun', 'maddah', 'hamzah', 'hamzat_al_wasl', 'omitted_alif', 'small_waw', 'small_yaa', 'small_noon', 'dot', 'two_dots', 'three_dots', 'rounded_zero', 'rectangular_zero', 'waqf_jaiz_mustawi_al_tarafayn', 'waqf_jaiz_waqf_awla', 'waqf_jaiz_wasl_awla', 'waqf_lazim', 'waqf_al_muanaqah', 'saktah', 'small_meem', 'hizb', 'sajdah', 'sajdah_mark', 'sajdah_line', 'seen_al_qiraah', 'tashil', 'ishmam', 'imalah'];
+const KIND_NAMES = ['body', 'mark', 'ayah-number', 'ayah-ornament', 'header-ink'];
+const FAMILY_NAMES = ['none', 'diacritic', 'tanwin', 'dots', 'waqf', 'sifr', 'sajdah', 'reading_sign'];
+const CATEGORY_NAMES = ['none', 'harakah', 'tanwin', 'letter_dot', 'orthographic', 'dabt', 'waqf', 'reading_sign', 'standalone'];
+const DECO_NAMES = ['ayah-mark', 'surah-name', 'basmalah', 'division-mark', 'sajdah-mark', 'page-number', 'running-head'];
+export function markId(name: string | number): number {
+  if (typeof name === 'number') return name;
+  const i = MARKS.indexOf(name);
+  return i < 0 ? 255 : i;
+}
+const named = (v: string | number, names: string[]) => (typeof v === 'number' ? v : Math.max(0, names.indexOf(v)));
+
+// ── colours ──────────────────────────────────────────────────────────────────────────────────
+export type Color = string | number;
+/** Any accepted colour ('#rgb' | '#rrggbb' | '#rrggbbaa' | 0xRRGGBBAA) → '#rrggbbaa'. */
+export function css(c: Color | null | undefined): string | undefined {
+  if (c == null) return undefined;
+  if (typeof c === 'number') return '#' + (c >>> 0).toString(16).padStart(8, '0');
+  let h = c.trim().replace(/^#/, '');
+  if (h.length === 3) h = h.split('').map(x => x + x).join('');
+  if (h.length === 6) h += 'ff';
+  return '#' + h.toLowerCase();
+}
+/** Colour with a replaced alpha (0..1). */
+export function rgba(c: Color, alpha: number): string {
+  const h = css(c)!;
+  return h.slice(0, 7) + Math.round(Math.max(0, Math.min(1, alpha)) * 255).toString(16).padStart(2, '0');
+}
+
+// ── targets and selectors (same shapes as web/qvp.js T / Sel) ────────────────────────────────
+export interface TargetObj { kind: number; a?: number; b?: number; c?: number; words?: number[] }
+/** 'page' | '2:255' | '2:255:3' | '2:255-257' | 'line:7' | 'surah:2' | word index | [indices] | T.* */
+export type Target = string | number | number[] | TargetObj;
+export const T = {
+  page: (): TargetObj => ({ kind: 0 }),
+  word: (i: number): TargetObj => ({ kind: 1, a: i }),
+  words: (ws: number[]): TargetObj => ({ kind: 2, words: ws }),
+  ayah: (s: number, a: number): TargetObj => ({ kind: 3, a: s, b: a }),
+  ayahRange: (s: number, a: number, b: number): TargetObj => ({ kind: 4, a: s, b: a, c: b }),
+  line: (n: number): TargetObj => ({ kind: 5, a: n }),
+  surah: (s: number): TargetObj => ({ kind: 6, a: s }),
+  range: (a: number, b: number): TargetObj => ({ kind: 7, a, b }),
+};
+export interface Selector { kind: number; a?: number; b?: number; c?: number; mark?: string }
+export const Sel = {
+  page: (): Selector => ({ kind: 0 }),
+  path: (p: number): Selector => ({ kind: 1, a: p }),
+  wordPath: (w: number, nth: number): Selector => ({ kind: 2, a: w, b: nth }),
+  /** nth mark of the word (0-based, marks only) */
+  wordMark: (w: number, nth: number): Selector => ({ kind: 3, a: w, b: nth }),
+  wordMarkNamed: (w: number, mark: string, nth = 0): Selector => ({ kind: 4, a: w, b: markId(mark), c: nth, mark }),
+  wordBody: (w: number): Selector => ({ kind: 5, a: w }),
+  wordMarks: (w: number): Selector => ({ kind: 6, a: w }),
+  word: (w: number): Selector => ({ kind: 7, a: w }),
+  ayah: (s: number, a: number): Selector => ({ kind: 8, a: s, b: a }),
+  line: (n: number): Selector => ({ kind: 9, a: n }),
+  mark: (m: string | number): Selector => ({ kind: 10, a: markId(m) }),
+  category: (c: string | number): Selector => ({ kind: 11, a: named(c, CATEGORY_NAMES) }),
+  family: (f: string | number): Selector => ({ kind: 12, a: named(f, FAMILY_NAMES) }),
+  kind: (k: string | number): Selector => ({ kind: 13, a: named(k, KIND_NAMES) }),
+  deco: (k: string | number): Selector => ({ kind: 14, a: named(k, DECO_NAMES) }),
+  decoIdx: (d: number): Selector => ({ kind: 15, a: d }),
+};
+
+// ── records ──────────────────────────────────────────────────────────────────────────────────
+export type Form = 'rasmUthmani' | 'rasmImlai' | 'qpc' | 'rasm' | 'search';
+export type HighlightMode = 'ink' | 'band' | 'both';
+export type MaskMode = 'hide' | 'block' | 'blur';
+export type DivisionKind = 'juz' | 'hizb' | 'nisf' | 'rubuAlHizb';
+export interface WordPath { idx: number; kind: number; kindName: string; mark: number; markName: string; nthMark: number; nthInWord: number; category: number; categoryName: string; family: number; familyName: string; line: number }
+export interface Word {
+  idx: number; surah: number; ayah: number; word: number; line: number; lineIdx: number; ayahIdx: number;
+  x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number;
+  wordKey: string; ayahKey: string; forms: Partial<Record<Form, string>>; label: string; paths: WordPath[];
+}
+export interface Deco { idx: number; kind: number; kindName: string; surah: number; ayah: number; line: number; x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number }
+export interface Hit { word: number; path: number; deco: number; line: number; distance: number; exact: boolean; wordKey: string | null; ayahKey: string | null }
+export interface Ayah { idx: number; surah: number; ayah: number; fragment: number; fragments: number; flags: number; rubuAlHizb: number; firstWord: number; nWords: number; ayahMarkDeco: number; bbox: number[] }
+export interface Line { idx: number; lineNo: number; isHeader: boolean; firstWord: number; nWords: number; bbox: number[]; bandY0: number; bandY1: number; centre: number }
+export interface SelectionInfo { words: number[]; text: string; citation: string; textWithCitation: string }
+export interface PageInfo { page: number; width: number; height: number; nLines: number; nAyahs: number; nWords: number; nPaths: number; nDecos: number; naturalPitch: number; forms: Form[]; loadMs: number; bytes: number; uri?: string }
+export interface Match { word: number; index: number; loose: boolean; wordKey: string; text: string }
+export interface Surah { number: number; ayahCount: number; hasBanner: boolean; hasBasmalah: boolean; place: string; bannerDeco: number; arabic: string; latin: string; english: string }
+export interface Division { kind: DivisionKind; n: number; surah: number; ayah: number; line: number; ayahIdx: number }
+export interface Marker { deco: number; surah: number; ayah: number; line: number; cx: number; cy: number; r: number; ornamentPath: number; numeralPath: number }
+export interface Rosette { deco: number; surah: number; ayah: number; juz: number; hizb: number; nisf: number; rubuAlHizb: number; rubuAlHizbInHizb: number }
+export interface Sajdah { deco: number; surah: number; ayah: number; signPath: number }
+export interface CropBox { x0: number; y0: number; x1: number; y1: number; nWords: number; ayahMarkDeco: number }
+export interface Layout { scale: number; ox: number; oy: number; contentW: number; contentH: number; pitch: number; lineDy: number[]; slots: number[][] }
+export interface Stats { loadMs: number; bytes: number; baseMs: number; overlayMs: number; basePaths: number; overlayPaths: number; bands: number; hitUs: number; animating: boolean; styleHandles: number; highlightHandles: number; engineVersion: number; viewScale: number; layout: Layout | null }
+export interface AtlasSurah { n: number; number: number; page: number; ayahCount: number; place: string; arabic: string; latin: string; english: string }
+export interface AtlasRubuAlHizb { rubuAlHizb: number; surah: number; ayah: number; page: number; ayahKey: string }
+
+export interface HighlightStyle { mode?: HighlightMode; ink?: Color; band?: Color; height?: 'pitch' | 'ink'; padX?: number; padY?: number; radius?: number; seam?: number; ms?: number; layer?: number }
+/** One declarative highlight; the native side keeps id → handle and calls highlight / rehighlight / restyleHighlight / unhighlight on diff. */
+export interface Highlight { id: string; target: Target; style?: HighlightStyle }
+/** One declarative style rule: `selector` (→ page.style) or `target` (→ page.styleTarget); `hide` → page.hide(selector). */
+export interface StyleRule { id: string; selector?: Selector; target?: Target; color?: Color; ms?: number; layer?: number; hide?: boolean }
+export interface Theme { ink?: Color; diacritics?: Color; dots?: Color; waqf?: Color; sifr?: Color; ayahMark?: Color; numeral?: Color; headers?: Color; marks?: Record<string, Color>; ms?: number }
+export interface Mask { target: Target; mode?: MaskMode; blockColor?: Color; padX?: number; padY?: number; radius?: number; reverse?: boolean }
+/** Greyed-page reveal: `revealStart(lit, byAyah, grey, ink, ayahMarks, ms)` then `revealGoto(at)` whenever `at` changes; null → revealStop. */
+export interface Reveal { lit?: number; byAyah?: boolean; grey?: Color; ink?: Color; ayahMarks?: boolean; ms?: number; at?: number }
+
+// ── the view ─────────────────────────────────────────────────────────────────────────────────
+export interface QvpPageViewProps extends ViewProps {
+  /** 'asset://pages/042.qvp' | 'file:///…' | '/abs/path' | 'base64:…' — the package ships no page data. */
+  pageUri?: string;
+  pageBase64?: string;
+  /** optional NNN.words.json sidecar (derived forms), same URI schemes */
+  wordsUri?: string;
+  padTop?: number; padBottom?: number; padSide?: number;
+  lineSpacing?: number; lineGap?: number; fillHeight?: boolean;
+  paperColor?: Color; defaultInk?: Color; selectionBand?: Color;
+  selectionEnabled?: boolean; zoomEnabled?: boolean; hitMaxDistance?: number;
+  theme?: Theme | null;
+  styles?: StyleRule[];
+  highlights?: Highlight[];
+  mask?: Mask | null;
+  reveal?: Reveal | null;
+  onWordTap?: (e: { word: Word; hit: Hit }) => void;
+  onDecoTap?: (e: { deco: Deco; hit: Hit }) => void;
+  onEmptyTap?: () => void;
+  onSelectionChanged?: (e: SelectionInfo) => void;
+  onPageLoad?: (e: PageInfo) => void;
+  onRevealChanged?: (e: { steps: number; at: number | null }) => void;
+  onError?: (e: { message: string }) => void;
+}
+type NativeProps = ViewProps & Omit<QvpPageViewProps, 'onWordTap' | 'onDecoTap' | 'onEmptyTap' | 'onSelectionChanged' | 'onPageLoad' | 'onRevealChanged' | 'onError'> & {
+  onWordTap?: (e: NativeSyntheticEvent<{ word: Word; hit: Hit }>) => void;
+  onDecoTap?: (e: NativeSyntheticEvent<{ deco: Deco; hit: Hit }>) => void;
+  onEmptyTap?: (e: NativeSyntheticEvent<{}>) => void;
+  onSelectionChanged?: (e: NativeSyntheticEvent<SelectionInfo>) => void;
+  onPageLoad?: (e: NativeSyntheticEvent<PageInfo>) => void;
+  onRevealChanged?: (e: NativeSyntheticEvent<{ steps: number; at: number | null }>) => void;
+  onError?: (e: NativeSyntheticEvent<{ message: string }>) => void;
+};
+const NativeQvpPageView = requireNativeComponent<NativeProps>('QvpPageView') as HostComponent<NativeProps>;
+
+const colorKeys = ['ink', 'band', 'diacritics', 'dots', 'waqf', 'sifr', 'ayahMark', 'numeral', 'headers', 'color', 'blockColor', 'grey'];
+function normColors<X>(o: X): X {
+  if (o == null || typeof o !== 'object') return o;
+  if (Array.isArray(o)) return o.map(normColors) as X;
+  const out: any = {};
+  for (const [k, v] of Object.entries(o as any)) {
+    if (colorKeys.includes(k) && (typeof v === 'string' || typeof v === 'number')) out[k] = css(v);
+    else if (k === 'marks' && v && typeof v === 'object') out[k] = Object.fromEntries(Object.entries(v as any).map(([m, c]) => [m, css(c as Color)]));
+    else if (k === 'style' || k === 'target' || k === 'selector') out[k] = k === 'style' ? normColors(v) : v;
+    else out[k] = v;
+  }
+  return out;
+}
+
+/** Imperative handle: the page-bound module API plus the react tag. */
+export type QvpPageViewHandle = PageApi & { tag: () => number };
+
+export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(function QvpPageView(props, ref) {
+  const native = useRef<any>(null);
+  const { theme, styles, highlights, mask, reveal, paperColor, defaultInk, selectionBand, onWordTap, onDecoTap, onEmptyTap, onSelectionChanged, onPageLoad, onRevealChanged, onError, ...rest } = props;
+  const tag = () => findNodeHandle(native.current) ?? -1;
+  useImperativeHandle(ref, () => ({ tag, ...bindPage(tag) }), []);
+  const nTheme = useMemo(() => (theme ? normColors(theme) : null), [theme]);
+  const nStyles = useMemo(() => (styles ? normColors(styles) : []), [styles]);
+  const nHighlights = useMemo(() => (highlights ? normColors(highlights) : []), [highlights]);
+  const nMask = useMemo(() => (mask ? normColors(mask) : null), [mask]);
+  const nReveal = useMemo(() => (reveal ? normColors(reveal) : null), [reveal]);
+  return (
+    <NativeQvpPageView
+      ref={native}
+      {...rest}
+      paperColor={css(paperColor)}
+      defaultInk={css(defaultInk)}
+      selectionBand={css(selectionBand)}
+      theme={nTheme}
+      styles={nStyles}
+      highlights={nHighlights}
+      mask={nMask}
+      reveal={nReveal}
+      onWordTap={onWordTap ? e => onWordTap(e.nativeEvent) : undefined}
+      onDecoTap={onDecoTap ? e => onDecoTap(e.nativeEvent) : undefined}
+      onEmptyTap={onEmptyTap ? () => onEmptyTap() : undefined}
+      onSelectionChanged={onSelectionChanged ? e => onSelectionChanged(e.nativeEvent) : undefined}
+      onPageLoad={onPageLoad ? e => onPageLoad(e.nativeEvent) : undefined}
+      onRevealChanged={onRevealChanged ? e => onRevealChanged(e.nativeEvent) : undefined}
+      onError={onError ? e => onError(e.nativeEvent) : undefined}
+    />
+  );
+});
+
+// ── the module ───────────────────────────────────────────────────────────────────────────────
+const M = NativeModules.QvpModule as any;
+if (!M) throw new Error('@quran.ws/qvp-react-native: native module QvpModule not linked (Android only for now; see README)');
+
+export interface SearchOptions { form?: Form; mode?: 'includes' | 'exact' | 'prefix'; normalize?: boolean; loose?: boolean; limit?: number }
+export interface TextOptions { form?: Form; wordSep?: string; lineSep?: string }
+export interface CropOptions { pad?: number; keepAyahMarks?: boolean; background?: Color }
+export interface HitOptions { maxDistance?: number; gapBias?: number; exactFirst?: boolean }
+
+/** Page-bound queries; `tag` is the react tag of a mounted `<QvpPageView />` (`findNodeHandle`). */
+export const Qvp = {
+  info: (tag: number): Promise<PageInfo> => M.info(tag),
+  words: (tag: number): Promise<Word[]> => M.words(tag),
+  word: (tag: number, idx: number): Promise<Word | null> => M.word(tag, idx),
+  ayahs: (tag: number): Promise<Ayah[]> => M.ayahs(tag),
+  lines: (tag: number): Promise<Line[]> => M.lines(tag),
+  decos: (tag: number): Promise<Deco[]> => M.decos(tag),
+  findWord: (tag: number, s: number, a: number, w: number): Promise<number> => M.findWord(tag, s, a, w),
+  resolve: (tag: number, target: Target): Promise<number[]> => M.resolve(tag, target),
+  wordForm: (tag: number, idx: number, form: Form = 'rasmUthmani'): Promise<string> => M.wordForm(tag, idx, form),
+  hasForm: (tag: number, form: Form): Promise<boolean> => M.hasForm(tag, form),
+  attachWords: (tag: number, json: string | object): Promise<number> => M.attachWords(tag, typeof json === 'string' ? json : JSON.stringify(json)),
+  surahs: (tag: number): Promise<Surah[]> => M.surahs(tag),
+  divisions: (tag: number): Promise<Division[]> => M.divisions(tag),
+  ayahMarks: (tag: number): Promise<Marker[]> => M.ayahMarks(tag),
+  rosettes: (tag: number): Promise<Rosette[]> => M.rosettes(tag),
+  sajdahs: (tag: number): Promise<Sajdah[]> => M.sajdahs(tag),
+  ayahKeys: (tag: number): Promise<{ surah: number; ayah: number; ayahKey: string }[]> => M.ayahKeys(tag),
+  ayahWordCount: (tag: number, s: number, a: number): Promise<{ count: number; complete: boolean }> => M.ayahWordCount(tag, s, a),
+  reciteMap: (tag: number, s: number, a: number, nSegments: number): Promise<number[] | null> => M.reciteMap(tag, s, a, nSegments),
+  wordLabel: (tag: number, i: number): Promise<string> => M.wordLabel(tag, i),
+  ayahLabel: (tag: number, i: number): Promise<string> => M.ayahLabel(tag, i),
+  text: (tag: number, target: Target = 'page', opts?: TextOptions): Promise<string> => M.text(tag, target, opts ?? null),
+  search: (tag: number, query: string, opts?: SearchOptions): Promise<Match[]> => M.search(tag, query, opts ?? null),
+  citation: (tag: number, words: number[]): Promise<string> => M.citation(tag, words),
+  hitTestViewEx: (tag: number, x: number, y: number, opts?: HitOptions): Promise<Hit | null> => M.hitTestViewEx(tag, x, y, opts ?? null),
+  wordBoxView: (tag: number, i: number): Promise<{ x0: number; y0: number; x1: number; y1: number } | null> => M.wordBoxView(tag, i),
+  currentLayout: (tag: number): Promise<Layout | null> => M.currentLayout(tag),
+  relayout: (tag: number): Promise<void> => M.relayout(tag),
+  resetView: (tag: number): Promise<void> => M.resetView(tag),
+  stats: (tag: number): Promise<Stats | null> => M.stats(tag),
+  select: (tag: number, anchor: number, focus: number = anchor): Promise<SelectionInfo> => M.select(tag, anchor, focus),
+  clearSelection: (tag: number): Promise<void> => M.clearSelection(tag),
+  selection: (tag: number): Promise<SelectionInfo> => M.selection(tag),
+  selectionText: (tag: number, form: Form = 'rasmUthmani', citation = false): Promise<string> => M.selectionText(tag, form, citation),
+  revealNext: (tag: number, n = 1): Promise<number> => M.revealNext(tag, n),
+  hideBack: (tag: number, n = 1): Promise<number> => M.hideBack(tag, n),
+  revealWord: (tag: number, i: number): Promise<boolean> => M.revealWord(tag, i),
+  hideWord: (tag: number, i: number): Promise<boolean> => M.hideWord(tag, i),
+  revealAll: (tag: number): Promise<void> => M.revealAll(tag),
+  hideAll: (tag: number): Promise<void> => M.hideAll(tag),
+  maskHidden: (tag: number): Promise<number[]> => M.maskHidden(tag),
+  maskWords: (tag: number): Promise<number[]> => M.maskWords(tag),
+  revealSteps: (tag: number): Promise<number> => M.revealSteps(tag),
+  revealAt: (tag: number): Promise<number | null> => M.revealAt(tag),
+  revealStepOf: (tag: number, i: number): Promise<number> => M.revealStepOf(tag, i),
+  cropBox: (tag: number, target: Target, opts?: CropOptions): Promise<CropBox | null> => M.cropBox(tag, target, opts ?? null),
+  cropSvg: (tag: number, target: Target, opts?: CropOptions): Promise<string | null> => M.cropSvg(tag, target, opts ? { ...opts, background: css(opts.background) } : null),
+
+  // engine-wide
+  strip: (s: string): Promise<string> => M.arabic('strip', s),
+  fold: (s: string): Promise<string> => M.arabic('fold', s),
+  normalize: (s: string): Promise<string> => M.arabic('normalize', s),
+  looseKey: (s: string): Promise<string> => M.arabic('loose', s),
+  arabic: (kind: 'strip' | 'fold' | 'normalize' | 'loose', s: string): Promise<string> => M.arabic(kind, s),
+  gapToFill: (pageW: number, pageH: number, lines: number, viewW: number, viewH: number, max = 0): Promise<number> => M.gapToFill(pageW, pageH, lines, viewW, viewH, max),
+  wastedFraction: (pageW: number, pageH: number, viewW: number, viewH: number): Promise<number> => M.wastedFraction(pageW, pageH, viewW, viewH),
+  markName: (m: number): string => MARKS[m] ?? 'unknown',
+  kindName: (k: number): string => KIND_NAMES[k] ?? 'other',
+  categoryName: (c: number): string => CATEGORY_NAMES[c] ?? '',
+  familyName: (f: number): string => FAMILY_NAMES[f] ?? '',
+  version: (M.getConstants?.().version ?? 0) as number,
+
+  // atlas
+  loadAtlas: (uri: string): Promise<number> => M.loadAtlas(uri),
+  freeAtlas: (id: number): Promise<void> => M.freeAtlas(id),
+  atlasPageOf: (id: number, s: number, a: number): Promise<number | null> => M.atlasPageOf(id, s, a),
+  atlasPageRange: (id: number, page: number): Promise<{ first: { surah: number; ayah: number }; last: { surah: number; ayah: number } } | null> => M.atlasPageRange(id, page),
+  atlasPages: (id: number): Promise<number> => M.atlasPages(id),
+  atlasSurah: (id: number, n: number): Promise<AtlasSurah | null> => M.atlasSurah(id, n),
+  atlasSurahs: (id: number): Promise<AtlasSurah[]> => M.atlasSurahs(id),
+  atlasPageOfSurah: (id: number, n: number): Promise<number | null> => M.atlasPageOfSurah(id, n),
+  atlasDivision: (id: number, kind: DivisionKind, n: number): Promise<AtlasRubuAlHizb | null> => M.atlasDivision(id, kind, n),
+  atlasDivisionAt: (id: number, kind: DivisionKind, s: number, a: number): Promise<number | null> => M.atlasDivisionAt(id, kind, s, a),
+  atlasJuzAt: (id: number, s: number, a: number): Promise<number | null> => M.atlasJuzAt(id, s, a),
+  atlasPagesOfJuz: (id: number, n: number): Promise<[number, number] | null> => M.atlasPagesOfJuz(id, n),
+  atlasFindSurah: (id: number, text: string): Promise<AtlasSurah[]> => M.atlasFindSurah(id, text),
+};
+
+/** Cross-page lookup (atlas.qva). `const atlas = await QvpAtlas.load('asset://pages/atlas.qva')`. */
+export class QvpAtlas {
+  private constructor(public readonly id: number) {}
+  static async load(uri: string): Promise<QvpAtlas> { return new QvpAtlas(await Qvp.loadAtlas(uri)); }
+  free() { return Qvp.freeAtlas(this.id); }
+  pageOf(s: number, a: number) { return Qvp.atlasPageOf(this.id, s, a); }
+  pageRange(page: number) { return Qvp.atlasPageRange(this.id, page); }
+  pages() { return Qvp.atlasPages(this.id); }
+  surah(n: number) { return Qvp.atlasSurah(this.id, n); }
+  surahs() { return Qvp.atlasSurahs(this.id); }
+  pageOfSurah(n: number) { return Qvp.atlasPageOfSurah(this.id, n); }
+  division(kind: DivisionKind, n: number) { return Qvp.atlasDivision(this.id, kind, n); }
+  juz(n: number) { return Qvp.atlasDivision(this.id, 'juz', n); }
+  hizb(n: number) { return Qvp.atlasDivision(this.id, 'hizb', n); }
+  rubuAlHizb(n: number) { return Qvp.atlasDivision(this.id, 'rubuAlHizb', n); }
+  divisionAt(kind: DivisionKind, s: number, a: number) { return Qvp.atlasDivisionAt(this.id, kind, s, a); }
+  juzAt(s: number, a: number) { return Qvp.atlasJuzAt(this.id, s, a); }
+  pagesOfJuz(n: number) { return Qvp.atlasPagesOfJuz(this.id, n); }
+  findSurah(text: string) { return Qvp.atlasFindSurah(this.id, text); }
+}
+
+type Tail<F> = F extends (tag: number, ...rest: infer R) => infer Ret ? (...rest: R) => Ret : never;
+const pageMethods = ['info', 'words', 'word', 'ayahs', 'lines', 'decos', 'findWord', 'resolve', 'wordForm', 'hasForm', 'attachWords', 'surahs', 'divisions', 'ayahMarks', 'rosettes', 'sajdahs', 'ayahKeys', 'ayahWordCount', 'reciteMap', 'wordLabel', 'ayahLabel', 'text', 'search', 'citation', 'hitTestViewEx', 'wordBoxView', 'currentLayout', 'relayout', 'resetView', 'stats', 'select', 'clearSelection', 'selection', 'selectionText', 'revealNext', 'hideBack', 'revealWord', 'hideWord', 'revealAll', 'hideAll', 'maskHidden', 'maskWords', 'revealSteps', 'revealAt', 'revealStepOf', 'cropBox', 'cropSvg'] as const;
+type PageMethod = (typeof pageMethods)[number];
+export type PageApi = { [K in PageMethod]: Tail<(typeof Qvp)[K]> };
+function bindPage(tag: () => number): PageApi {
+  const out: any = {};
+  for (const k of pageMethods) out[k] = (...args: any[]) => (Qvp[k] as any)(tag(), ...args);
+  return out;
+}
+
+/**
+ * `const qvp = useQvp(); <QvpPageView ref={qvp.ref} … />; await qvp.search('الله')`
+ * The page-bound API without passing a tag around.
+ */
+export function useQvp(): PageApi & { ref: React.RefObject<QvpPageViewHandle | null>; tag: () => number } {
+  const ref = useRef<QvpPageViewHandle | null>(null);
+  return useMemo(() => {
+    const tag = () => ref.current?.tag() ?? -1;
+    return { ref, tag, ...bindPage(tag) };
+  }, []);
+}
+
+export default QvpPageView;