@quran.ws/qvp-react-native 0.1.0 → 0.3.1

package/src/index.tsx

@@ -2,7 +2,7 @@
  * @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.
+ * to the Kotlin library (`ws.quran.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.
  */
@@ -20,20 +20,9 @@ import {
 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 DECORATION = { 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;
@@ -53,38 +42,38 @@ export function rgba(c: Color, alpha: number): string {
 }
 
 // ── targets and selectors (same shapes as web/qvp.js T / Sel) ────────────────────────────────
-export interface TargetObj { kind: number; a?: number; b?: number; c?: number; words?: number[] }
+export interface TargetObj { target: 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 }),
+  page: (): TargetObj => ({ target: 0 }),
+  word: (i: number): TargetObj => ({ target: 1, a: i }),
+  words: (ws: number[]): TargetObj => ({ target: 2, words: ws }),
+  ayah: (s: number, a: number): TargetObj => ({ target: 3, a: s, b: a }),
+  ayahRange: (s: number, a: number, b: number): TargetObj => ({ target: 4, a: s, b: a, c: b }),
+  line: (n: number): TargetObj => ({ target: 5, a: n }),
+  surah: (s: number): TargetObj => ({ target: 6, a: s }),
+  range: (a: number, b: number): TargetObj => ({ target: 7, a, b }),
 };
-export interface Selector { kind: number; a?: number; b?: number; c?: number; mark?: string }
+export interface Selector { selector: 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 }),
+  page: (): Selector => ({ selector: 0 }),
+  path: (p: number): Selector => ({ selector: 1, a: p }),
+  wordPath: (w: number, nth: number): Selector => ({ selector: 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 }),
+  wordMark: (w: number, nth: number): Selector => ({ selector: 3, a: w, b: nth }),
+  wordMarkNamed: (w: number, mark: string, nth = 0): Selector => ({ selector: 4, a: w, b: markId(mark), c: nth, mark }),
+  wordBody: (w: number): Selector => ({ selector: 5, a: w }),
+  wordMarks: (w: number): Selector => ({ selector: 6, a: w }),
+  word: (w: number): Selector => ({ selector: 7, a: w }),
+  ayah: (s: number, a: number): Selector => ({ selector: 8, a: s, b: a }),
+  line: (n: number): Selector => ({ selector: 9, a: n }),
+  mark: (m: string | number): Selector => ({ selector: 10, a: markId(m) }),
+  category: (c: string | number): Selector => ({ selector: 11, a: named(c, CATEGORY_NAMES) }),
+  family: (f: string | number): Selector => ({ selector: 12, a: named(f, FAMILY_NAMES) }),
+  kind: (k: string | number): Selector => ({ selector: 13, a: named(k, KIND_NAMES) }),
+  decoration: (k: string | number): Selector => ({ selector: 14, a: named(k, DECORATION_NAMES) }),
+  decorationIndex: (d: number): Selector => ({ selector: 15, a: d }),
 };
 
 // ── records ──────────────────────────────────────────────────────────────────────────────────
@@ -92,41 +81,49 @@ 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 WordPath { index: 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;
+  index: number; surah: number; ayah: number; word: number; line: number; lineIndex: number; ayahIndex: 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 Deco { index: number; decoration: number; decorationName: string; surah: number; ayah: number; line: number; x0: number; y0: number; x1: number; y1: number; text: string; firstPath: number; nPaths: number }
+/** The one hit shape for every hit test; the exact variants report distance 0 and `isExact`. */
+export interface Hit { word: number; path: number; decoration: number; line: number; distance: number; isExact: boolean; wordKey: string | null; ayahKey: string | null }
+export interface Ayah { index: number; surah: number; ayah: number; fragment: number; fragments: number; flags: number; rubuAlHizb: number; firstWord: number; nWords: number; ayahMarkDecoration: number; bbox: number[] }
+export interface Line { index: number; lineNumber: 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 PageInfo { page: number; width: number; height: number; nLines: number; nAyahs: number; nWords: number; nPaths: number; nDecorations: number; lineSpacing: number; forms: Form[]; loadMs: number; bytes: number; uri?: string }
+export interface Match { word: number; index: number; isLooseMatch: boolean; wordKey: string; text: string }
+export interface Surah { number: number; ayahCount: number; hasBanner: boolean; hasBasmalah: boolean; place: string; bannerDecoration: number; arabic: string; latin: string; english: string }
+export interface Division { division: DivisionKind; number: number; surah: number; ayah: number; line: number; ayahIndex: number }
+export interface Marker { decoration: number; surah: number; ayah: number; line: number; cx: number; cy: number; r: number; ornamentPath: number; numeralPath: number }
+export interface SurahHeader { decoration: number; surah: number; line: number; x0: number; y0: number; x1: number; y1: number; titleX0: number; titleY0: number; titleX1: number; titleY1: number }
+export interface Rosette { decoration: number; surah: number; ayah: number; juz: number; hizb: number; nisf: number; rubuAlHizb: number; rubuAlHizbInHizb: number }
+export interface Sajdah { decoration: number; surah: number; ayah: number; signPath: number }
+export interface CropBox { x0: number; y0: number; x1: number; y1: number; nWords: number; ayahMarkDecoration: number }
+export interface Layout { scale: number; offsetX: number; offsetY: number; contentW: number; contentH: number; lineSpacing: 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: string; viewScale: number; layout: Layout | null }
+export interface AtlasSurah { 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 HighlightStyle { mode?: HighlightMode; ink?: Color; band?: Color; height?: 'lineSpacing' | '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 / moveHighlight / restyleHighlight / removeHighlight 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 }
+/** `from` masks every word from that index to the end of the page instead of `target`. */
+export interface Mask { target?: Target; from?: number; 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 ─────────────────────────────────────────────────────────────────────────────────
+/** What a pinch does to the page: the engine owns the policy, this names which one. */
+export type ZoomMode = 'stepped' | 'continuous' | 'magnify';
+/** Where the reader's zoom control stands: the mode, the step, and the size in force. */
+export interface Zoom { mode: ZoomMode; step: number; zoom: number }
+
 export interface QvpPageViewProps extends ViewProps {
   /** 'asset://pages/042.qvp' | 'file:///…' | '/abs/path' | 'base64:…' — the package ships no page data. */
   pageUri?: string;
@@ -134,29 +131,47 @@ export interface QvpPageViewProps extends ViewProps {
   /** optional NNN.words.json sidecar (derived forms), same URI schemes */
   wordsUri?: string;
   padTop?: number; padBottom?: number; padSide?: number;
-  lineSpacing?: number; lineGap?: number; fillHeight?: boolean;
+  /** spacing only opens up: lineSpacing < 1 is clamped by the engine */
+  lineSpacing?: number; fillHeight?: boolean;
+  /** Draw source-native frames around surah names on the printed page. */
+  surahFrames?: boolean;
   paperColor?: Color; defaultInk?: Color; selectionBand?: Color;
   selectionEnabled?: boolean; zoomEnabled?: boolean; hitMaxDistance?: number;
+  /** What a pinch does to the page. `stepped` reflows onto the page's own zoom steps and is
+   * the default a reader gets; `continuous` reflows to the zoom the fingers ask for; `magnify`
+   * scales the printed page and leaves the rows alone. */
+  zoomMode?: ZoomMode;
+  /** The step to sit on: 0 is the printed page, 1 upwards the page's own steps. Leave it out
+   * to let the reader's pinch drive it. */
+  zoomStep?: 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;
+  onDecorationTap?: (e: { decoration: Deco; hit: Hit }) => void;
   onEmptyTap?: () => void;
   onSelectionChanged?: (e: SelectionInfo) => void;
   onPageLoad?: (e: PageInfo) => void;
   onRevealChanged?: (e: { steps: number; at: number | null }) => void;
+  /** A sideways flick the engine read as a page turn, in pages, in reading order: a mushaf is
+   * read right to left, so a flick to the right gives +1. Which page that is belongs to the
+   * app, so the view turns nothing by itself. */
+  onSwipe?: (e: { pages: number }) => void;
+  /** The size the reader is at changed: a pinch committed, or a step was asked for. */
+  onZoomChanged?: (e: Zoom) => void;
   onError?: (e: { message: string }) => void;
 }
-type NativeProps = ViewProps & Omit<QvpPageViewProps, 'onWordTap' | 'onDecoTap' | 'onEmptyTap' | 'onSelectionChanged' | 'onPageLoad' | 'onRevealChanged' | 'onError'> & {
+type NativeProps = ViewProps & Omit<QvpPageViewProps, 'onWordTap' | 'onDecorationTap' | 'onEmptyTap' | 'onSelectionChanged' | 'onPageLoad' | 'onRevealChanged' | 'onSwipe' | 'onZoomChanged' | 'onError'> & {
   onWordTap?: (e: NativeSyntheticEvent<{ word: Word; hit: Hit }>) => void;
-  onDecoTap?: (e: NativeSyntheticEvent<{ deco: Deco; hit: Hit }>) => void;
+  onDecorationTap?: (e: NativeSyntheticEvent<{ decoration: 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;
+  onSwipe?: (e: NativeSyntheticEvent<{ pages: number }>) => void;
+  onZoomChanged?: (e: NativeSyntheticEvent<Zoom>) => void;
   onError?: (e: NativeSyntheticEvent<{ message: string }>) => void;
 };
 const NativeQvpPageView = requireNativeComponent<NativeProps>('QvpPageView') as HostComponent<NativeProps>;
@@ -180,7 +195,7 @@ 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 { theme, styles, highlights, mask, reveal, paperColor, defaultInk, selectionBand, onWordTap, onDecorationTap, onEmptyTap, onSelectionChanged, onPageLoad, onRevealChanged, onSwipe, onZoomChanged, onError, ...rest } = props;
   const tag = () => findNodeHandle(native.current) ?? -1;
   useImperativeHandle(ref, () => ({ tag, ...bindPage(tag) }), []);
   const nTheme = useMemo(() => (theme ? normColors(theme) : null), [theme]);
@@ -200,54 +215,77 @@ export const QvpPageView = forwardRef<QvpPageViewHandle, QvpPageViewProps>(funct
       highlights={nHighlights}
       mask={nMask}
       reveal={nReveal}
-      onWordTap={onWordTap ? e => onWordTap(e.nativeEvent) : undefined}
-      onDecoTap={onDecoTap ? e => onDecoTap(e.nativeEvent) : undefined}
+      onWordTap={onWordTap ? (e: NativeSyntheticEvent<{ word: Word; hit: Hit }>) => onWordTap(e.nativeEvent) : undefined}
+      onDecorationTap={onDecorationTap ? (e: NativeSyntheticEvent<{ decoration: Deco; hit: Hit }>) => onDecorationTap(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}
+      onSelectionChanged={onSelectionChanged ? (e: NativeSyntheticEvent<SelectionInfo>) => onSelectionChanged(e.nativeEvent) : undefined}
+      onPageLoad={onPageLoad ? (e: NativeSyntheticEvent<PageInfo>) => onPageLoad(e.nativeEvent) : undefined}
+      onRevealChanged={onRevealChanged ? (e: NativeSyntheticEvent<{ steps: number; at: number | null }>) => onRevealChanged(e.nativeEvent) : undefined}
+      onSwipe={onSwipe ? (e: NativeSyntheticEvent<{ pages: number }>) => onSwipe(e.nativeEvent) : undefined}
+      onZoomChanged={onZoomChanged ? (e: NativeSyntheticEvent<Zoom>) => onZoomChanged(e.nativeEvent) : undefined}
+      onError={onError ? (e: NativeSyntheticEvent<{ message: string }>) => onError(e.nativeEvent) : undefined}
     />
   );
 });
 
 // ── the module ───────────────────────────────────────────────────────────────────────────────
 const M = NativeModules.QvpModule as any;
+
+// The engine's name tables, read through the native module's constants; no table lives here.
+const NAMES = (M.getConstants?.() ?? {}) as { marks?: string[]; kinds?: string[]; families?: string[]; categories?: string[]; decorations?: string[]; divisions?: string[]; places?: string[] };
+const KIND_NAMES: string[] = NAMES.kinds ?? [];
+const FAMILY_NAMES: string[] = NAMES.families ?? [];
+const CATEGORY_NAMES: string[] = NAMES.categories ?? [];
+const DECORATION_NAMES: string[] = NAMES.decorations ?? [];
+export const MARKS: string[] = NAMES.marks ?? [];
+/** A name's id in a table; 255 when the table has no such name. */
+export type NameTable = 'marks' | 'kinds' | 'families' | 'categories' | 'decorations' | 'divisions' | 'places';
+const named = (v: string | number, names: string[]) => { if (typeof v === 'number') return v; const i = names.indexOf(v); return i < 0 ? 255 : i; };
+export function markId(name: string | number): number { return named(name, MARKS); }
 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 SearchOptions { form?: Form; mode?: 'includes' | 'exact' | 'prefix'; normalize?: boolean; looseMatch?: 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 }
+export interface HitOptions { maxDistance?: number; gapBias?: number; preferExact?: 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),
+  word: (tag: number, index: number): Promise<Word | null> => M.word(tag, index),
   ayahs: (tag: number): Promise<Ayah[]> => M.ayahs(tag),
   lines: (tag: number): Promise<Line[]> => M.lines(tag),
-  decos: (tag: number): Promise<Deco[]> => M.decos(tag),
+  decorations: (tag: number): Promise<Deco[]> => M.decorations(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),
+  targetWords: (tag: number, target: Target): Promise<number[]> => M.targetWords(tag, target),
+  wordForm: (tag: number, index: number, form: Form = 'rasmUthmani'): Promise<string> => M.wordForm(tag, index, 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),
+  surahHeaders: (tag: number): Promise<SurahHeader[]> => M.surahHeaders(tag),
+  surahHeadersView: (tag: number): Promise<SurahHeader[]> => M.surahHeadersView(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),
+  ayahWordCount: (tag: number, s: number, a: number): Promise<{ count: number; isComplete: 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),
+  hitTestExact: (tag: number, x: number, y: number): Promise<Hit | null> => M.hitTestExact(tag, x, y),
+  hitTest: (tag: number, x: number, y: number, opts?: HitOptions): Promise<Hit | null> => M.hitTest(tag, x, y, opts ?? null),
+  hitTestExactView: (tag: number, x: number, y: number): Promise<Hit | null> => M.hitTestExactView(tag, x, y),
+  hitTestView: (tag: number, x: number, y: number, opts?: HitOptions): Promise<Hit | null> => M.hitTestView(tag, x, y, opts ?? null),
+  layoutLineSpacingToFill: (tag: number, max = 0): Promise<number> => M.layoutLineSpacingToFill(tag, max),
+  layoutWastedFraction: (tag: number): Promise<number> => M.layoutWastedFraction(tag),
+  layoutPrintedHeight: (tag: number): Promise<number> => M.layoutPrintedHeight(tag),
+  grid: (tag: number): Promise<{ lines: number; lineSpacing: number }> => M.grid(tag),
+  wordBoundsView: (tag: number, i: number): Promise<{ x0: number; y0: number; x1: number; y1: number } | null> => M.wordBoundsView(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),
@@ -255,19 +293,19 @@ export const Qvp = {
   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),
+  selectionText: (tag: number, form: Form = 'rasmUthmani', includeCitation = false): Promise<string> => M.selectionText(tag, form, includeCitation),
+  unmaskNext: (tag: number, n = 1): Promise<number> => M.unmaskNext(tag, n),
+  maskBack: (tag: number, n = 1): Promise<number> => M.maskBack(tag, n),
+  unmaskWord: (tag: number, i: number): Promise<boolean> => M.unmaskWord(tag, i),
+  maskWord: (tag: number, i: number): Promise<boolean> => M.maskWord(tag, i),
+  unmaskAll: (tag: number): Promise<void> => M.unmaskAll(tag),
+  maskAll: (tag: number): Promise<void> => M.maskAll(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),
+  revealStepCount: (tag: number): Promise<number> => M.revealStepCount(tag),
+  revealPosition: (tag: number): Promise<number | null> => M.revealPosition(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),
+  cropBounds: (tag: number, target: Target, opts?: CropOptions): Promise<CropBox | null> => M.cropBounds(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
@@ -275,29 +313,34 @@ export const Qvp = {
   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),
+  arabic: (op: 'strip' | 'fold' | 'normalize' | 'loose', s: string): Promise<string> => M.arabic(op, s),
+  markCategory: (m: number): Promise<number> => M.markCategory(m),
+  engineName: (): Promise<string> => M.engineName(),
+  /** How many ids a name table has, and a name's id in it (255 when absent); the tables come from the engine at start. */
+  nameCount: (table: NameTable): number => (NAMES[table] ?? []).length,
+  nameId: (table: NameTable, name: string): number => named(name, NAMES[table] ?? []),
   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,
+  /** The engine version, e.g. '0.2.0', and the page format version it reads. */
+  version: (M.getConstants?.().version ?? '') as string,
+  formatVersion: (M.getConstants?.().formatVersion ?? 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),
+  atlasPageCount: (id: number): Promise<number> => M.atlasPageCount(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),
+  atlasDivision: (id: number, division: DivisionKind, n: number): Promise<AtlasRubuAlHizb | null> => M.atlasDivision(id, division, n),
+  atlasDivisionOf: (id: number, division: DivisionKind, s: number, a: number): Promise<number | null> => M.atlasDivisionOf(id, division, s, a),
+  atlasJuzOf: (id: number, s: number, a: number): Promise<number | null> => M.atlasJuzOf(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),
+  atlasSearchSurahs: (id: number, text: string): Promise<AtlasSurah[]> => M.atlasSearchSurahs(id, text),
 };
 
 /** Cross-page lookup (atlas.qva). `const atlas = await QvpAtlas.load('asset://pages/atlas.qva')`. */
@@ -307,22 +350,22 @@ export class QvpAtlas {
   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); }
+  pageCount() { return Qvp.atlasPageCount(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); }
+  division(division: DivisionKind, n: number) { return Qvp.atlasDivision(this.id, division, 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); }
+  divisionOf(division: DivisionKind, s: number, a: number) { return Qvp.atlasDivisionOf(this.id, division, s, a); }
+  juzOf(s: number, a: number) { return Qvp.atlasJuzOf(this.id, s, a); }
   pagesOfJuz(n: number) { return Qvp.atlasPagesOfJuz(this.id, n); }
-  findSurah(text: string) { return Qvp.atlasFindSurah(this.id, text); }
+  searchSurahs(text: string) { return Qvp.atlasSearchSurahs(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;
+const pageMethods = ['info', 'words', 'word', 'ayahs', 'lines', 'decorations', 'findWord', 'targetWords', 'wordForm', 'hasForm', 'attachWords', 'surahs', 'divisions', 'surahHeaders', 'surahHeadersView', 'ayahMarks', 'rosettes', 'sajdahs', 'ayahKeys', 'ayahWordCount', 'reciteMap', 'wordLabel', 'ayahLabel', 'text', 'search', 'citation', 'hitTestExact', 'hitTest', 'hitTestExactView', 'hitTestView', 'layoutLineSpacingToFill', 'layoutWastedFraction', 'layoutPrintedHeight', 'grid', 'wordBoundsView', 'currentLayout', 'relayout', 'resetView', 'stats', 'select', 'clearSelection', 'selection', 'selectionText', 'unmaskNext', 'maskBack', 'unmaskWord', 'maskWord', 'unmaskAll', 'maskAll', 'maskHidden', 'maskWords', 'revealStepCount', 'revealPosition', 'revealStepOf', 'cropBounds', 'cropSvg'] as const;
 type PageMethod = (typeof pageMethods)[number];
 export type PageApi = { [K in PageMethod]: Tail<(typeof Qvp)[K]> };
 function bindPage(tag: () => number): PageApi {