@quran.ws/engine 0.1.0 → 0.3.0

package/web/qvp.js

@@ -6,14 +6,26 @@
   'use strict';
 
   const NONE = 0xffffffff;
+// the reader's zoom control: what a pinch does to the page
+const ZOOM_MODE = { stepped: 0, continuous: 1, magnify: 2 };
+const ZOOM_MODE_NAME = ['stepped', 'continuous', 'magnify'];
+  /** The defaults every wrapper shares (QVP_DEFAULT_* in qvp.h; the parity check compares them). */
+  const DEFAULTS = { INK: 0x231f20ff, HIGHLIGHT_INK: 0x1a73e8ff, HIGHLIGHT_BAND: 0xd6a3264d, HIGHLIGHT_PAD_X: 1.2, HIGHLIGHT_PAD_Y: 0, HIGHLIGHT_SEAM: 0.25,
+    SELECTION_BAND: 0x2d6fd640, GAP_BIAS: 0.6, TAP_DISTANCE: 6, GRID_LINES: 15, ASPECT_SLACK: 1.15, MASK_BLOCK: 0xd9d4c8ff, MASK_PAD: 0.6, MASK_RADIUS: 0.8,
+    REVEAL_LIT: 1, REVEAL_GREY: 0xc9c4b8ff, CROP_PAD: 2,
+    MIN_ZOOM: 0.5, MAX_ZOOM: 12, ZOOMED_THRESHOLD: 1.02, SWIPE_AXIS_RATIO: 1.5, SWIPE_DISTANCE: 40, SWIPE_VELOCITY: 500,
+    ZOOM_SNAP_HYSTERESIS: 0.03, ZOOM_QUANTUM: 0.01 };
   const KIND = { BODY: 0, MARK: 1, AYAH_NUMBER: 2, AYAH_MARK_ORNAMENT: 3, HEADER_INK: 4, ORNAMENT: 5, PAGE_NUMBER: 6, RUNNING_HEAD: 7, OTHER: 255 };
   const FAMILY = { NONE: 0, DIACRITIC: 1, TANWIN: 2, DOTS: 3, WAQF: 4, SIFR: 5, SAJDAH: 6, READING_SIGN: 7 };
   const CATEGORY = { NONE: 0, HARAKAH: 1, TANWIN: 2, LETTER_DOT: 3, ORTHOGRAPHIC: 4, DABT: 5, WAQF: 6, READING_SIGN: 7, STANDALONE: 8 };
-  const DECO = { AYAH_MARK: 0, SURAH_NAME: 1, BASMALAH: 2, DIVISION_MARK: 3, SAJDAH_MARK: 4, PAGE_NUMBER: 5, RUNNING_HEAD: 6, OTHER: 255 };
+  const DECORATION = { AYAH_MARK: 0, SURAH_NAME: 1, BASMALAH: 2, DIVISION_MARK: 3, SAJDAH_MARK: 4, PAGE_NUMBER: 5, RUNNING_HEAD: 6, OTHER: 255 };
   const FORM = { rasm_uthmani: 0, rasm_imlai: 1, qpc: 2, rasm: 3, search: 4 };
   const LAYER = { BASE: 0, THEME: 10, HIGHLIGHT: 50, SELECTION: 60, TOP: 100 };
-  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 MARK = Object.fromEntries(MARKS.map((n, i) => [n, i]).filter(([n]) => n));
+  // The engine's name tables (QVP_NAMES_*), read from the engine when it is initialised.
+  const NAMES_TABLE = { mark: 0, kind: 1, family: 2, category: 3, decoration: 4, division: 5, place: 6 };
+  let NAMES = null;
+  const names = table => { if (!NAMES) throw new Error('QvpEngine.init() first: names come from the engine'); return NAMES[table]; };
+  const idOf = (table, v) => { if (typeof v !== 'string') return v; const i = names(table).indexOf(v); return i < 0 ? 255 : i; };
 
   // colours: numbers are 0xRRGGBBAA; strings '#rgb', '#rrggbb', '#rrggbbaa'
   function rgba(c, alpha) {
@@ -28,35 +40,35 @@
 
   // Selectors (what a style rule applies to)
   const Sel = {
-    page: () => ({ kind: 0 }),
-    path: i => ({ kind: 1, a: i }),
-    wordPath: (w, n) => ({ kind: 2, a: w, b: n }),
-    wordMark: (w, n) => ({ kind: 3, a: w, b: n }),                    // nth mark of the word (0-based)
-    wordMarkNamed: (w, mark, n = 0) => ({ kind: 4, a: w, b: markId(mark), c: n }),
-    wordBody: w => ({ kind: 5, a: w }),
-    wordMarks: w => ({ kind: 6, a: w }),
-    word: w => ({ kind: 7, a: w }),
-    ayah: (s, a) => ({ kind: 8, a: s, b: a }),
-    line: n => ({ kind: 9, a: n }),
-    mark: m => ({ kind: 10, a: markId(m) }),
-    category: c => ({ kind: 11, a: typeof c === 'string' ? CATEGORY[c.toUpperCase().replace('-', '_')] : c }),
-    family: f => ({ kind: 12, a: typeof f === 'string' ? FAMILY[f.toUpperCase().replace('-', '_')] : f }),
-    kind: k => ({ kind: 13, a: typeof k === 'string' ? KIND[k.toUpperCase()] : k }),
-    deco: k => ({ kind: 14, a: typeof k === 'string' ? DECO[k.toUpperCase().replace('-', '_')] : k }),
-    decoIdx: i => ({ kind: 15, a: i }),
+    page: () => ({ selector: 0 }),
+    path: i => ({ selector: 1, a: i }),
+    wordPath: (w, n) => ({ selector: 2, a: w, b: n }),
+    wordMark: (w, n) => ({ selector: 3, a: w, b: n }),                    // nth mark of the word (0-based)
+    wordMarkNamed: (w, mark, n = 0) => ({ selector: 4, a: w, b: markId(mark), c: n }),
+    wordBody: w => ({ selector: 5, a: w }),
+    wordMarks: w => ({ selector: 6, a: w }),
+    word: w => ({ selector: 7, a: w }),
+    ayah: (s, a) => ({ selector: 8, a: s, b: a }),
+    line: n => ({ selector: 9, a: n }),
+    mark: m => ({ selector: 10, a: markId(m) }),
+    category: c => ({ selector: 11, a: idOf('category', c) }),
+    family: f => ({ selector: 12, a: idOf('family', f) }),
+    kind: k => ({ selector: 13, a: idOf('kind', k) }),
+    decoration: k => ({ selector: 14, a: idOf('decoration', k) }),
+    decorationIndex: i => ({ selector: 15, a: i }),
   };
-  const markId = m => (typeof m === 'string' ? (MARK[m] ?? 255) : m);
+  const markId = m => idOf('mark', m);
 
   // Targets (what resolves to a word list). Strings: 'page', '2:255', '2:255:3', '2:255-257', 'line:7', 'surah:2'
   const T = {
-    page: () => ({ kind: 0 }),
-    word: i => ({ kind: 1, a: i }),
-    words: ws => ({ kind: 2, words: ws }),
-    ayah: (s, a) => ({ kind: 3, a: s, b: a }),
-    ayahRange: (s, a, b) => ({ kind: 4, a: s, b: a, c: b }),
-    line: n => ({ kind: 5, a: n }),
-    surah: s => ({ kind: 6, a: s }),
-    range: (a, b) => ({ kind: 7, a, b }),
+    page: () => ({ target: 0 }),
+    word: i => ({ target: 1, a: i }),
+    words: ws => ({ target: 2, words: ws }),
+    ayah: (s, a) => ({ target: 3, a: s, b: a }),
+    ayahRange: (s, a, b) => ({ target: 4, a: s, b: a, c: b }),
+    line: n => ({ target: 5, a: n }),
+    surah: s => ({ target: 6, a: s }),
+    range: (a, b) => ({ target: 7, a, b }),
   };
 
   class QvpEngine {
@@ -69,27 +81,63 @@
       this.mem = this.ex.memory;
       this.scratch = this.ex.qvp_alloc(1 << 16);   // 64 KB for outputs
       this.scratch2 = this.ex.qvp_alloc(1 << 16);  // 64 KB for inputs
+      this._buf = 0; this._bufLen = 0;             // grown on demand for the bigger reads
       this.td = new TextDecoder();
       this.te = new TextEncoder();
+      // Load every name table from the engine once; Sel and markId read them.
+      NAMES = Object.fromEntries(Object.entries(NAMES_TABLE).map(([k, t]) => [k, this.names(t)]));
     }
+    /** All names of a table (QVP_NAMES_* id or key), index = id. */
+    names(table) { const t = typeof table === 'string' ? NAMES_TABLE[table] : table; const n = this.ex.qvp_name_count(t); return Array.from({ length: n }, (_, i) => this.name(t, i)); }
+    nameCount(table) { return this.ex.qvp_name_count(typeof table === 'string' ? NAMES_TABLE[table] : table); }
+    name(table, id) { this.ex.qvp_name(typeof table === 'string' ? NAMES_TABLE[table] : table, id, this.scratch); return this.qstr(this.scratch); }
+    nameId(table, s) { const [p, n] = this.putStr(s); return this.ex.qvp_name_id(typeof table === 'string' ? NAMES_TABLE[table] : table, p, n); }
     dv() { return new DataView(this.mem.buffer); }
     str(ptr, len) { return this.td.decode(new Uint8Array(this.mem.buffer, ptr, len)); }
     qstr(at) { const d = this.dv(); return this.str(d.getUint32(at, true), d.getUint32(at + 4, true)); }
+    /** the reader's pan and zoom: {scale, offsetX, offsetY} in, the same out. The engine owns
+     * the arithmetic so every platform pinches alike; the host owns only the gesture. */
+    _putView(v, at) { const d = this.dv(); d.setFloat32(at, v.scale, true); d.setFloat32(at + 4, v.offsetX, true); d.setFloat32(at + 8, v.offsetY, true); return at; }
+    _getView(at) { const d = this.dv(); return { scale: d.getFloat32(at, true), offsetX: d.getFloat32(at + 4, true), offsetY: d.getFloat32(at + 8, true) }; }
+    /** zoom about a point of the viewport (the point between two fingers), clamped */
+    viewZoomAbout(view, focalX, focalY, factor, { min = 0, max = 0 } = {}) {
+      const i = this._putView(view, this.scratch2 + 32768);
+      this.ex.qvp_view_zoom_about(i, focalX, focalY, factor, min, max, this.scratch);
+      return this._getView(this.scratch);
+    }
+    /** move by a drag, in viewport px */
+    viewPan(view, dx, dy) { const i = this._putView(view, this.scratch2 + 32768); this.ex.qvp_view_pan(i, dx, dy, this.scratch); return this._getView(this.scratch); }
+    /** hold the content against the viewport: centre what does not fill it, cover what does */
+    viewClamp(view, contentW, contentH, viewportW, viewportH) { const i = this._putView(view, this.scratch2 + 32768); this.ex.qvp_view_clamp(i, contentW, contentH, viewportW, viewportH, this.scratch); return this._getView(this.scratch); }
+    /** +1 or -1 when a released drag is a page swipe, 0 when it is not */
+    viewSwipe(dx, dy, vx = 0, vy = 0) { return this.ex.qvp_view_swipe(dx, dy, vx, vy); }
+    /** how many pages a released drag turns, in reading order: a mushaf runs right to left, so a
+     * flick to the right is the next page. Add it to the page you are on. */
+    swipePages(dx, dy, vx = 0, vy = 0) { return this.ex.qvp_swipe_pages(dx, dy, vx, vy); }
+    /** a scratch buffer of at least `len` bytes, kept between calls */
+    buf(len) { if (len > this._bufLen) { this._buf = this.ex.qvp_alloc(len); this._bufLen = len; } return this._buf; }
     /** write a JS string into scratch2 at offset; returns [ptr, len] */
     putStr(s, off = 0) { const b = this.te.encode(s); new Uint8Array(this.mem.buffer, this.scratch2 + off, b.length).set(b); return [this.scratch2 + off, b.length]; }
     putU32(arr, off = 0) { const p = this.scratch2 + off; new Uint32Array(this.mem.buffer, p, arr.length).set(arr); return p; }
     nameOf(fn, v) { this.ex[fn](v, this.scratch); return this.qstr(this.scratch); }
-    markName(m) { return MARKS[m] || 'unknown'; }
+    markName(m) { return this.nameOf('qvp_mark_name', m); }
     familyName(f) { return this.nameOf('qvp_family_name', f); }
     kindName(k) { return this.nameOf('qvp_kind_name', k); }
     categoryName(c) { return this.nameOf('qvp_category_name', c); }
     markCategory(m) { return this.ex.qvp_mark_category(markId(m)); }
+    markFromName(s) { const [p, n] = this.putStr(s); return this.ex.qvp_mark_from_name(p, n); }
+    /** The engine version, e.g. '0.2.0'. */
+    version() { this.ex.qvp_version(this.scratch); return this.qstr(this.scratch); }
+    /** The page format version the engine reads. */
+    formatVersion() { return this.ex.qvp_format_version(); }
+    /** The engine's name, `qvp` (a NUL-terminated C string in wasm memory). */
+    engineName() { const p = this.ex.qvp_engine_name(), u = new Uint8Array(this.mem.buffer); let n = 0; while (u[p + n]) n++; return this.str(p, n); }
     /** Arabic text tools */
     strip(s) { return this._arabic(0, s); }
     fold(s) { return this._arabic(1, s); }
     normalize(s) { return this._arabic(2, s); }
     looseKey(s) { return this._arabic(3, s); }
-    _arabic(kind, s) { const [p, n] = this.putStr(s); this.ex.qvp_arabic(kind, p, n, this.scratch); return this.qstr(this.scratch); }
+    _arabic(op, s) { const [p, n] = this.putStr(s); this.ex.qvp_arabic(op, p, n, this.scratch); return this.qstr(this.scratch); }
     loadPage(bytes) {
       const p = this.ex.qvp_alloc(bytes.length);
       new Uint8Array(this.mem.buffer, p, bytes.length).set(bytes);
@@ -106,15 +154,13 @@
       if (!h) throw new Error('qvp_atlas_load failed');
       return new QvpAtlas(this, h);
     }
-    gapToFill(pageW, pageH, lines, viewW, viewH, max = 0) { return this.ex.qvp_gap_to_fill(pageW, pageH, lines, viewW, viewH, max); }
-    wastedFraction(pageW, pageH, viewW, viewH) { return this.ex.qvp_wasted_fraction(pageW, pageH, viewW, viewH); }
   }
 
   // struct writers (wasm32 layouts, see qvp.h)
   function writeTarget(e, at, t) {
     if (typeof t === 'string') t = parseTarget(t);
     const d = e.dv();
-    d.setUint8(at, t.kind); d.setUint32(at + 4, t.a >>> 0 || 0, true); d.setUint32(at + 8, t.b >>> 0 || 0, true); d.setUint32(at + 12, t.c >>> 0 || 0, true);
+    d.setUint8(at, t.target); d.setUint32(at + 4, t.a >>> 0 || 0, true); d.setUint32(at + 8, t.b >>> 0 || 0, true); d.setUint32(at + 12, t.c >>> 0 || 0, true);
     let wp = 0, wn = 0;
     if (t.words) { wp = e.putU32(Uint32Array.from(t.words), 1024); wn = t.words.length; }
     d.setUint32(at + 16, wp, true); d.setUint32(at + 20, wn, true);
@@ -126,16 +172,16 @@
     if ((m = /^line:(\d+)$/.exec(s))) return T.line(+m[1]);
     if ((m = /^surah:(\d+)$/.exec(s))) return T.surah(+m[1]);
     if ((m = /^(\d+):(\d+)-(\d+)$/.exec(s))) return T.ayahRange(+m[1], +m[2], +m[3]);
-    if ((m = /^(\d+):(\d+):(\d+)$/.exec(s))) return { kind: 1, wordKey: [+m[1], +m[2], +m[3]] };
+    if ((m = /^(\d+):(\d+):(\d+)$/.exec(s))) return { target: 1, wordKey: [+m[1], +m[2], +m[3]] };
     if ((m = /^(\d+):(\d+)$/.exec(s))) return T.ayah(+m[1], +m[2]);
     throw new Error('bad target ' + s);
   }
   function writeSel(e, at, s) {
     const d = e.dv();
-    d.setUint8(at, s.kind); d.setUint32(at + 4, s.a >>> 0 || 0, true); d.setUint32(at + 8, s.b >>> 0 || 0, true); d.setUint32(at + 12, s.c >>> 0 || 0, true);
+    d.setUint8(at, s.selector); d.setUint32(at + 4, s.a >>> 0 || 0, true); d.setUint32(at + 8, s.b >>> 0 || 0, true); d.setUint32(at + 12, s.c >>> 0 || 0, true);
     return at;
   }
-  const HL_DEFAULT = { mode: 'band', height: 'pitch', ink: '#1a73e8', band: rgba('#d6a326', 0.3), padX: 1.2, padY: 0, radius: 0, seam: 0.25, ms: 0, layer: LAYER.HIGHLIGHT };
+  const HL_DEFAULT = { mode: 'band', height: 'lineSpacing', ink: DEFAULTS.HIGHLIGHT_INK, band: DEFAULTS.HIGHLIGHT_BAND, padX: DEFAULTS.HIGHLIGHT_PAD_X, padY: DEFAULTS.HIGHLIGHT_PAD_Y, radius: 0, seam: DEFAULTS.HIGHLIGHT_SEAM, ms: 0, layer: LAYER.HIGHLIGHT };
   function writeHl(e, at, st) {
     st = { ...HL_DEFAULT, ...st };
     const d = e.dv();
@@ -158,7 +204,7 @@
       ex.qvp_page_info(handle, s);
       let d = engine.dv();
       this.width = d.getFloat32(s, true); this.height = d.getFloat32(s + 4, true); this.page = d.getUint32(s + 8, true);
-      this.nLines = d.getUint32(s + 12, true); this.nAyahs = d.getUint32(s + 16, true); this.nWords = d.getUint32(s + 20, true); this.nPaths = d.getUint32(s + 24, true); this.nDecos = d.getUint32(s + 28, true);
+      this.nLines = d.getUint32(s + 12, true); this.nAyahs = d.getUint32(s + 16, true); this.nWords = d.getUint32(s + 20, true); this.nPaths = d.getUint32(s + 24, true); this.nDecorations = d.getUint32(s + 28, true);
       ex.qvp_geometry(handle, s);
       d = engine.dv();
       const opsPtr = d.getUint32(s, true), opsLen = d.getUint32(s + 4, true), ptsPtr = d.getUint32(s + 8, true), ptsLen = d.getUint32(s + 12, true), tabPtr = d.getUint32(s + 16, true), nPaths = d.getUint32(s + 20, true);
@@ -169,10 +215,10 @@
       this.words = Array.from({ length: this.nWords }, (_, i) => this._word(i));
       this.ayahs = Array.from({ length: this.nAyahs }, (_, i) => this._ayah(i));
       this.lines = Array.from({ length: this.nLines }, (_, i) => this._line(i));
-      this.decos = Array.from({ length: this.nDecos }, (_, i) => this._deco(i));
-      this.naturalPitch = ex.qvp_natural_pitch(handle);
+      this.decorations = Array.from({ length: this.nDecorations }, (_, i) => this._deco(i));
+      this.lineSpacing = ex.qvp_page_line_spacing(handle);
       this.currentLayout = null;
-      this._defaultInk = 0x231f20ff;
+      this._defaultInk = DEFAULTS.INK;
     }
     free() { this.e.ex.qvp_page_free(this.h); this.h = 0; }
 
@@ -211,25 +257,25 @@
     _word(i) {
       const ex = this.e.ex, s = this.e.scratch; if (!ex.qvp_word_info(this.h, i, s)) return null;
       const d = this.e.dv();
-      return { idx: i, surah: d.getUint16(s, true), ayah: d.getUint16(s + 2, true), word: d.getUint16(s + 4, true), line: d.getUint16(s + 6, true), ayahIdx: d.getUint32(s + 8, true), lineIdx: d.getUint32(s + 12, true),
+      return { index: i, surah: d.getUint16(s, true), ayah: d.getUint16(s + 2, true), word: d.getUint16(s + 4, true), line: d.getUint16(s + 6, true), ayahIndex: d.getUint32(s + 8, true), lineIndex: d.getUint32(s + 12, true),
         x0: d.getFloat32(s + 16, true), y0: d.getFloat32(s + 20, true), x1: d.getFloat32(s + 24, true), y1: d.getFloat32(s + 28, true), text: this.e.qstr(s + 32), firstPath: d.getUint32(s + 40, true), nPaths: d.getUint32(s + 44, true) };
     }
     _ayah(i) {
       const ex = this.e.ex, s = this.e.scratch; if (!ex.qvp_ayah_info(this.h, i, s)) return null;
       const d = this.e.dv();
-      return { idx: i, surah: d.getUint16(s, true), ayah: d.getUint16(s + 2, true), fragment: d.getUint8(s + 4), fragments: d.getUint8(s + 5), flags: d.getUint8(s + 6), rubuAlHizb: d.getUint16(s + 8, true),
-        firstWord: d.getUint32(s + 12, true), nWords: d.getUint32(s + 16, true), ayahMarkDeco: d.getUint32(s + 20, true), x0: d.getFloat32(s + 24, true), y0: d.getFloat32(s + 28, true), x1: d.getFloat32(s + 32, true), y1: d.getFloat32(s + 36, true) };
+      return { index: i, surah: d.getUint16(s, true), ayah: d.getUint16(s + 2, true), fragment: d.getUint8(s + 4), fragments: d.getUint8(s + 5), flags: d.getUint8(s + 6), rubuAlHizb: d.getUint16(s + 8, true),
+        firstWord: d.getUint32(s + 12, true), nWords: d.getUint32(s + 16, true), ayahMarkDecoration: d.getUint32(s + 20, true), x0: d.getFloat32(s + 24, true), y0: d.getFloat32(s + 28, true), x1: d.getFloat32(s + 32, true), y1: d.getFloat32(s + 36, true) };
     }
     _line(i) {
       const ex = this.e.ex, s = this.e.scratch; if (!ex.qvp_line_info(this.h, i, s)) return null;
       const d = this.e.dv();
-      return { idx: i, lineNo: d.getUint8(s), isHeader: !!d.getUint8(s + 1), firstWord: d.getUint32(s + 4, true), nWords: d.getUint32(s + 8, true), x0: d.getFloat32(s + 12, true), y0: d.getFloat32(s + 16, true), x1: d.getFloat32(s + 20, true), y1: d.getFloat32(s + 24, true),
+      return { index: i, lineNumber: d.getUint8(s), isHeader: !!d.getUint8(s + 1), firstWord: d.getUint32(s + 4, true), nWords: d.getUint32(s + 8, true), x0: d.getFloat32(s + 12, true), y0: d.getFloat32(s + 16, true), x1: d.getFloat32(s + 20, true), y1: d.getFloat32(s + 24, true),
         bandY0: d.getFloat32(s + 28, true), bandY1: d.getFloat32(s + 32, true), centre: d.getFloat32(s + 36, true) };
     }
     _deco(i) {
-      const ex = this.e.ex, s = this.e.scratch; if (!ex.qvp_deco_info(this.h, i, s)) return null;
+      const ex = this.e.ex, s = this.e.scratch; if (!ex.qvp_decoration_info(this.h, i, s)) return null;
       const d = this.e.dv();
-      return { idx: i, kind: d.getUint8(s), surah: d.getUint16(s + 2, true), ayah: d.getUint16(s + 4, true), line: d.getUint32(s + 8, true), x0: d.getFloat32(s + 12, true), y0: d.getFloat32(s + 16, true), x1: d.getFloat32(s + 20, true), y1: d.getFloat32(s + 24, true),
+      return { index: i, decoration: d.getUint8(s), surah: d.getUint16(s + 2, true), ayah: d.getUint16(s + 4, true), line: d.getUint32(s + 8, true), x0: d.getFloat32(s + 12, true), y0: d.getFloat32(s + 16, true), x1: d.getFloat32(s + 20, true), y1: d.getFloat32(s + 24, true),
         text: this.e.qstr(s + 28), firstPath: d.getUint32(s + 36, true), nPaths: d.getUint32(s + 40, true) };
     }
     wordForm(i, form = 'rasm_uthmani') { const s = this.e.scratch; if (!this.e.ex.qvp_word_form(this.h, i, FORM[form] ?? 0, s)) return ''; return this.e.qstr(s); }
@@ -240,37 +286,55 @@
       if (t instanceof Array) t = T.words(t);
       return writeTarget(this.e, this.e.scratch2 + 4096, t);
     }
-    resolve(t) { const n = this.e.ex.qvp_resolve(this.h, this._target(t), this.e.scratch, 16384); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 16384))); }
+    targetWords(t) { const n = this.e.ex.qvp_target_words(this.h, this._target(t), this.e.scratch, 16384); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 16384))); }
 
     // ── metadata ──
     surahs() {
-      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_surahs_count(this.h), out = [];
+      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_surah_count(this.h), out = [];
       for (let i = 0; i < n; i++) { ex.qvp_surah_at(this.h, i, s); const d = this.e.dv();
-        out.push({ number: d.getUint16(s, true), ayahCount: d.getUint16(s + 2, true), hasBanner: !!d.getUint8(s + 4), hasBasmalah: !!d.getUint8(s + 5), place: ['makkah', 'madinah'][d.getUint8(s + 6)] || '', bannerDeco: d.getUint32(s + 8, true), arabic: this.e.qstr(s + 12), latin: this.e.qstr(s + 20), english: this.e.qstr(s + 28) }); }
+        out.push({ number: d.getUint16(s, true), ayahCount: d.getUint16(s + 2, true), hasBanner: !!d.getUint8(s + 4), hasBasmalah: !!d.getUint8(s + 5), place: names('place')[d.getUint8(s + 6)] || '', bannerDecoration: d.getUint32(s + 8, true), arabic: this.e.qstr(s + 12), latin: this.e.qstr(s + 20), english: this.e.qstr(s + 28) }); }
       return out;
     }
     divisions() {
       const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_divisions(this.h, s, 64), d = this.e.dv(), out = [];
-      for (let i = 0; i < Math.min(n, 64); i++) { const o = s + i * 12; out.push({ kind: ['juz', 'hizb', 'nisf', 'rubu_al_hizb'][d.getUint8(o)], line: d.getUint8(o + 1), n: d.getUint16(o + 2, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), ayahIdx: d.getUint32(o + 8, true) }); }
+      for (let i = 0; i < Math.min(n, 64); i++) { const o = s + i * 12; out.push({ division: names('division')[d.getUint8(o)], line: d.getUint8(o + 1), number: d.getUint16(o + 2, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), ayahIndex: d.getUint32(o + 8, true) }); }
+      return out;
+    }
+    /** the surah headings in page units: the box a frame fills, and the title ink in it */
+    surahHeaders() {
+      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_surah_headers(this.h, s, 32), d = this.e.dv(), out = [];
+      for (let i = 0; i < Math.min(n, 32); i++) { const o = s + i * 44; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), line: d.getUint32(o + 8, true), x0: d.getFloat32(o + 12, true), y0: d.getFloat32(o + 16, true), x1: d.getFloat32(o + 20, true), y1: d.getFloat32(o + 24, true), titleX0: d.getFloat32(o + 28, true), titleY0: d.getFloat32(o + 32, true), titleX1: d.getFloat32(o + 36, true), titleY1: d.getFloat32(o + 40, true) }); }
+      return out;
+    }
+    /** the same, in viewport px through the current layout: what a host draws its own frame around */
+    surahHeadersView() {
+      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_surah_headers_view(this.h, s, 32), d = this.e.dv(), out = [];
+      for (let i = 0; i < Math.min(n, 32); i++) { const o = s + i * 44; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), line: d.getUint32(o + 8, true), x0: d.getFloat32(o + 12, true), y0: d.getFloat32(o + 16, true), x1: d.getFloat32(o + 20, true), y1: d.getFloat32(o + 24, true), titleX0: d.getFloat32(o + 28, true), titleY0: d.getFloat32(o + 32, true), titleX1: d.getFloat32(o + 36, true), titleY1: d.getFloat32(o + 40, true) }); }
       return out;
     }
     ayahMarks() {
       const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_ayah_marks(this.h, s, 128), d = this.e.dv(), out = [];
-      for (let i = 0; i < Math.min(n, 128); i++) { const o = s + i * 32; out.push({ deco: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), line: d.getUint32(o + 8, true), cx: d.getFloat32(o + 12, true), cy: d.getFloat32(o + 16, true), r: d.getFloat32(o + 20, true), ornamentPath: d.getUint32(o + 24, true), numeralPath: d.getUint32(o + 28, true) }); }
+      for (let i = 0; i < Math.min(n, 128); i++) { const o = s + i * 32; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), line: d.getUint32(o + 8, true), cx: d.getFloat32(o + 12, true), cy: d.getFloat32(o + 16, true), r: d.getFloat32(o + 20, true), ornamentPath: d.getUint32(o + 24, true), numeralPath: d.getUint32(o + 28, true) }); }
+      return out;
+    }
+    /** the ayah medallions in viewport px through the current layout: where each is drawn */
+    ayahMarksView() {
+      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_ayah_marks_view(this.h, s, 128), d = this.e.dv(), out = [];
+      for (let i = 0; i < Math.min(n, 128); i++) { const o = s + i * 32; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), line: d.getUint32(o + 8, true), cx: d.getFloat32(o + 12, true), cy: d.getFloat32(o + 16, true), r: d.getFloat32(o + 20, true), ornamentPath: d.getUint32(o + 24, true), numeralPath: d.getUint32(o + 28, true) }); }
       return out;
     }
     rosettes() {
       const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_rosettes(this.h, s, 32), d = this.e.dv(), out = [];
-      for (let i = 0; i < Math.min(n, 32); i++) { const o = s + i * 20; out.push({ deco: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), juz: d.getUint16(o + 8, true), hizb: d.getUint16(o + 10, true), nisf: d.getUint16(o + 12, true), rubuAlHizb: d.getUint16(o + 14, true), rubuAlHizbInHizb: d.getUint16(o + 16, true) }); }
+      for (let i = 0; i < Math.min(n, 32); i++) { const o = s + i * 20; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), juz: d.getUint16(o + 8, true), hizb: d.getUint16(o + 10, true), nisf: d.getUint16(o + 12, true), rubuAlHizb: d.getUint16(o + 14, true), rubuAlHizbInHizb: d.getUint16(o + 16, true) }); }
       return out;
     }
     sajdahs() {
       const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_sajdahs(this.h, s, 16), d = this.e.dv(), out = [];
-      for (let i = 0; i < Math.min(n, 16); i++) { const o = s + i * 12; out.push({ deco: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), signPath: d.getUint32(o + 8, true) }); }
+      for (let i = 0; i < Math.min(n, 16); i++) { const o = s + i * 12; out.push({ decoration: d.getUint32(o, true), surah: d.getUint16(o + 4, true), ayah: d.getUint16(o + 6, true), signPath: d.getUint32(o + 8, true) }); }
       return out;
     }
     ayahKeys() { const n = this.e.ex.qvp_ayah_keys(this.h, this.e.scratch, 256); const v = new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 256)); return Array.from(v, k => [k >>> 16, k & 0xffff]); }
-    ayahWordCount(surah, ayah) { const n = this.e.ex.qvp_ayah_word_count(this.h, surah, ayah, this.e.scratch); return { count: n, complete: !!this.e.dv().getUint32(this.e.scratch, true) }; }
+    ayahWordCount(surah, ayah) { const n = this.e.ex.qvp_ayah_word_count(this.h, surah, ayah, this.e.scratch); return { count: n, isComplete: !!this.e.dv().getUint8(this.e.scratch) }; }
     /** words for n recitation segments, or null when the counts disagree (follow the ayah whole) */
     reciteMap(surah, ayah, nSegments) { const n = this.e.ex.qvp_recite_map(this.h, surah, ayah, nSegments, this.e.scratch, 4096); return n < 0 ? null : Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, n)); }
     wordLabel(i) { this.e.ex.qvp_word_label(this.h, i, this.e.scratch); return this.e.qstr(this.e.scratch); }
@@ -279,14 +343,14 @@
     // ── text & search ──
     text(target = 'page', { form = 'rasm_uthmani', wordSep = ' ', lineSep = '\n' } = {}) {
       const [wp, wn] = this.e.putStr(wordSep, 0), [lp, ln] = this.e.putStr(lineSep, 256);
-      this.e.ex.qvp_text_target(this.h, this._target(target), FORM[form] ?? 0, wp, wn, lp, ln, this.e.scratch);
+      this.e.ex.qvp_text(this.h, this._target(target), FORM[form] ?? 0, wp, wn, lp, ln, this.e.scratch);
       return this.e.qstr(this.e.scratch);
     }
-    search(query, { form = 'search', mode = 'includes', normalize = true, loose = true, limit = 0 } = {}) {
+    search(query, { form = 'search', mode = 'includes', normalize = true, looseMatch = true, limit = 0 } = {}) {
       const [qp, qn] = this.e.putStr(query);
-      const n = this.e.ex.qvp_search(this.h, qp, qn, FORM[form] ?? 4, { includes: 0, exact: 1, prefix: 2 }[mode] ?? 0, normalize ? 1 : 0, loose ? 1 : 0, limit, this.e.scratch, 1024);
+      const n = this.e.ex.qvp_search(this.h, qp, qn, FORM[form] ?? 4, { includes: 0, exact: 1, prefix: 2 }[mode] ?? 0, normalize ? 1 : 0, looseMatch ? 1 : 0, limit, this.e.scratch, 1024);
       const d = this.e.dv(), out = [];
-      for (let i = 0; i < Math.min(n, 1024); i++) { const o = this.e.scratch + i * 12; const w = d.getUint32(o, true); out.push({ word: w, index: d.getUint32(o + 4, true), loose: !!d.getUint32(o + 8, true), wordKey: this.wordKey(w), text: this.words[w].text }); }
+      for (let i = 0; i < Math.min(n, 1024); i++) { const o = this.e.scratch + i * 12; const w = d.getUint32(o, true); out.push({ word: w, index: d.getUint32(o + 4, true), isLooseMatch: !!d.getUint8(o + 8), wordKey: this.wordKey(w), text: this.words[w].text }); }
       return out;
     }
     wordKey(i) { const w = this.words[i]; return `${w.surah}:${w.ayah}:${w.word}`; }
@@ -296,42 +360,245 @@
     citation(words) { const p = this.e.putU32(Uint32Array.from(words)); this.e.ex.qvp_citation(this.h, p, words.length, this.e.scratch); return this.e.qstr(this.e.scratch); }
 
     // ── hit testing ──
-    _hit(s) { const d = this.e.dv(); const f = v => (v === NONE ? -1 : v); return { word: f(d.getUint32(s, true)), path: f(d.getUint32(s + 4, true)), deco: f(d.getUint32(s + 8, true)) }; }
-    hitTest(x, y) { return this.e.ex.qvp_hit_test(this.h, x, y, this.e.scratch) ? this._hit(this.e.scratch) : null; }
-    hitTestView(vx, vy) { return this.e.ex.qvp_hit_test_view(this.h, vx, vy, this.e.scratch) ? this._hit(this.e.scratch) : null; }
-    _hitOpt(o) { const d = this.e.dv(), at = this.e.scratch2 + 8192; d.setFloat32(at, o.maxDistance ?? 0, true); d.setFloat32(at + 4, o.gapBias ?? 0.6, true); d.setUint32(at + 8, o.exactFirst === false ? 0 : 1, true); return at; }
-    _hitEx(s) { const d = this.e.dv(); const f = v => (v === NONE ? -1 : v); const h = { word: f(d.getUint32(s, true)), path: f(d.getUint32(s + 4, true)), deco: f(d.getUint32(s + 8, true)), line: d.getUint32(s + 12, true), distance: d.getFloat32(s + 16, true), exact: !!d.getUint32(s + 20, true) }; if (h.word >= 0) { h.wordKey = this.wordKey(h.word); const w = this.words[h.word]; h.ayahKey = `${w.surah}:${w.ayah}`; } return h; }
+    hitTestExact(x, y) { return this.e.ex.qvp_hit_test_exact(this.h, x, y, this.e.scratch) ? this._hit(this.e.scratch) : null; }
+    hitTestExactView(viewX, viewY) { return this.e.ex.qvp_hit_test_exact_view(this.h, viewX, viewY, this.e.scratch) ? this._hit(this.e.scratch) : null; }
+    _hitOpt(o) { const d = this.e.dv(), at = this.e.scratch2 + 8192; d.setFloat32(at, o.maxDistance ?? 0, true); d.setFloat32(at + 4, o.gapBias ?? 0.6, true); d.setUint8(at + 8, o.preferExact === false ? 0 : 1); return at; }
+    /** the one hit shape for every hit test; the exact variants report distance 0 and isExact */
+    _hit(s) { const d = this.e.dv(); const f = v => (v === NONE ? -1 : v); const h = { word: f(d.getUint32(s, true)), path: f(d.getUint32(s + 4, true)), decoration: f(d.getUint32(s + 8, true)), line: f(d.getUint32(s + 12, true)), distance: d.getFloat32(s + 16, true), isExact: !!d.getUint8(s + 20) }; if (h.word >= 0) { h.wordKey = this.wordKey(h.word); const w = this.words[h.word]; h.ayahKey = `${w.surah}:${w.ayah}`; } return h; }
     /** gap-aware: every point on a printed line resolves to the word the user meant */
-    hitTestEx(x, y, opt = {}) { return this.e.ex.qvp_hit_test_ex(this.h, x, y, this._hitOpt(opt), this.e.scratch) ? this._hitEx(this.e.scratch) : null; }
-    hitTestViewEx(vx, vy, opt = {}) { return this.e.ex.qvp_hit_test_view_ex(this.h, vx, vy, this._hitOpt(opt), this.e.scratch) ? this._hitEx(this.e.scratch) : null; }
-    lineBands() { const n = this.e.ex.qvp_line_bands(this.h, this.e.scratch, 64), d = this.e.dv(), out = []; for (let i = 0; i < Math.min(n, 64); i++) { const o = this.e.scratch + i * 28; out.push({ line: d.getUint32(o, true), lineNo: d.getUint32(o + 4, true), y0: d.getFloat32(o + 8, true), y1: d.getFloat32(o + 12, true), mid: d.getFloat32(o + 16, true), inkY0: d.getFloat32(o + 20, true), inkY1: d.getFloat32(o + 24, true) }); } return out; }
-    hitBoxes(gapBias = 0.6) { const n = this.e.ex.qvp_hit_boxes(this.h, gapBias, this.e.scratch, 1024), d = this.e.dv(), out = []; for (let i = 0; i < Math.min(n, 1024); i++) { const o = this.e.scratch + i * 40; out.push({ word: d.getUint32(o, true), line: d.getUint32(o + 4, true), x0: d.getFloat32(o + 8, true), y0: d.getFloat32(o + 12, true), x1: d.getFloat32(o + 16, true), y1: d.getFloat32(o + 20, true), inkX0: d.getFloat32(o + 24, true), inkY0: d.getFloat32(o + 28, true), inkX1: d.getFloat32(o + 32, true), inkY1: d.getFloat32(o + 36, true) }); } return out; }
+    hitTest(x, y, opt = {}) { return this.e.ex.qvp_hit_test(this.h, x, y, this._hitOpt(opt), this.e.scratch) ? this._hit(this.e.scratch) : null; }
+    hitTestView(viewX, viewY, opt = {}) { return this.e.ex.qvp_hit_test_view(this.h, viewX, viewY, this._hitOpt(opt), this.e.scratch) ? this._hit(this.e.scratch) : null; }
+    /** the hit boxes in viewport px through the current layout: what a tap is resolved with */
+    hitAreasView(gapBias = DEFAULTS.GAP_BIAS) { const n = this.e.ex.qvp_hit_areas_view(this.h, gapBias, this.e.scratch, 1024), d = this.e.dv(), out = []; for (let i = 0; i < Math.min(n, 1024); i++) { const o = this.e.scratch + i * 40; out.push({ word: d.getUint32(o, true), line: d.getUint32(o + 4, true), x0: d.getFloat32(o + 8, true), y0: d.getFloat32(o + 12, true), x1: d.getFloat32(o + 16, true), y1: d.getFloat32(o + 20, true), inkX0: d.getFloat32(o + 24, true), inkY0: d.getFloat32(o + 28, true), inkX1: d.getFloat32(o + 32, true), inkY1: d.getFloat32(o + 36, true) }); } return out; }
+    lineBands() { const n = this.e.ex.qvp_line_bands(this.h, this.e.scratch, 64), d = this.e.dv(), out = []; for (let i = 0; i < Math.min(n, 64); i++) { const o = this.e.scratch + i * 28; out.push({ line: d.getUint32(o, true), lineNumber: d.getUint32(o + 4, true), y0: d.getFloat32(o + 8, true), y1: d.getFloat32(o + 12, true), mid: d.getFloat32(o + 16, true), inkY0: d.getFloat32(o + 20, true), inkY1: d.getFloat32(o + 24, true) }); } return out; }
+    hitAreas(gapBias = DEFAULTS.GAP_BIAS) { const n = this.e.ex.qvp_hit_areas(this.h, gapBias, this.e.scratch, 1024), d = this.e.dv(), out = []; for (let i = 0; i < Math.min(n, 1024); i++) { const o = this.e.scratch + i * 40; out.push({ word: d.getUint32(o, true), line: d.getUint32(o + 4, true), x0: d.getFloat32(o + 8, true), y0: d.getFloat32(o + 12, true), x1: d.getFloat32(o + 16, true), y1: d.getFloat32(o + 20, true), inkX0: d.getFloat32(o + 24, true), inkY0: d.getFloat32(o + 28, true), inkX1: d.getFloat32(o + 32, true), inkY1: d.getFloat32(o + 36, true) }); } return out; }
 
     // ── layout ──
-    layout(spec) {
-      const ex = this.e.ex, s = this.e.scratch; let d = this.e.dv();
+    /** Write a layout spec (QvpLayoutSpec, 76 bytes) at scratch offset `s`. */
+    _writeLayoutSpec(spec, s) {
+      const d = this.e.dv();
       d.setFloat32(s, spec.viewportW, true); d.setFloat32(s + 4, spec.viewportH, true); d.setFloat32(s + 8, spec.padTop || 0, true); d.setFloat32(s + 12, spec.padBottom || 0, true);
-      d.setFloat32(s + 16, spec.padLeft || 0, true); d.setFloat32(s + 20, spec.padRight || 0, true); d.setFloat32(s + 24, spec.lineSpacing ?? 1, true); d.setFloat32(s + 28, spec.lineGap || 0, true);
-      d.setUint32(s + 32, spec.fillHeight ? 1 : 0, true); d.setUint32(s + 36, spec.nominalLines || 15, true);
-      ex.qvp_layout(this.h, s, s + 64);
-      d = this.e.dv(); const o = s + 64;
+      d.setFloat32(s + 16, spec.padLeft || 0, true); d.setFloat32(s + 20, spec.padRight || 0, true); d.setFloat32(s + 24, spec.lineSpacing ?? 1, true);
+      d.setUint8(s + 28, spec.fillHeight ? 1 : 0); d.setUint32(s + 32, spec.gridLines || 0, true);
+      d.setFloat32(s + 36, spec.cropLeft || 0, true); d.setFloat32(s + 40, spec.cropRight || 0, true); d.setFloat32(s + 44, spec.maxAspectSlack || 0, true);
+      const r = spec.reflow;
+      d.setFloat32(s + 48, r ? (r.zoom ?? 1) : 0, true);
+      // 255 asks the engine for its own default
+      const fill = { ragged: 0, justified: 1, centred: 2, centered: 2 }[r && r.fill] ?? 255;
+      const breaks = { greedy: 0, even: 1, fitted: 2 }[r && r.breaks] ?? 255;
+      d.setUint8(s + 52, fill); d.setUint8(s + 53, breaks); d.setUint8(s + 54, r && r.gaps === 'printed' ? 0 : 1);
+      d.setFloat32(s + 56, r ? (r.wordGap ?? 1) : 1, true);
+      d.setFloat32(s + 60, r ? (r.maxStretch ?? 0) : 0, true);
+      d.setFloat32(s + 64, r && r.relax !== undefined ? r.relax : -1, true);
+      // bannerZoom: how big a surah name or basmalah may get against its printed size as the
+      // reader zooms; 0 lets it grow with the page until it fills the row.
+      d.setFloat32(s + 68, spec.bannerZoom ?? 0, true);
+      // Native frames preserve the printed page by default; a host may supply its own.
+      d.setUint8(s + 72, spec.surahFrames === false ? 0 : 1);
+    }
+    /** Leading (page units) that makes the page fill the padded viewport of `spec`; max 0 = unlimited. */
+    layoutLineSpacingToFill(spec, max = 0) { const s = this.e.scratch; this._writeLayoutSpec(spec, s); return this.e.ex.qvp_layout_line_spacing_to_fill(this.h, s, max); }
+    /** the share of the padded viewport left empty when the page is fitted to width */
+    layoutWastedFraction(spec) { const s = this.e.scratch; this._writeLayoutSpec(spec, s); return this.e.ex.qvp_layout_wasted_fraction(this.h, s); }
+    /** the page's height laid out for `spec` at the printed pitch, in viewport px: contentH before fill-height adds leading, padding included */
+    layoutPrintedHeight(spec) { const s = this.e.scratch; this._writeLayoutSpec(spec, s); return this.e.ex.qvp_layout_printed_height(this.h, s); }
+    /** the grid this page is laid out inside: the mushaf's line count and the printed line spacing */
+    get grid() { this.e.ex.qvp_page_grid(this.h, this.e.scratch); const d = this.e.dv(); return { lines: d.getUint32(this.e.scratch, true), lineSpacing: d.getFloat32(this.e.scratch + 4, true) }; }
+    layout(spec) {
+      const ex = this.e.ex, s = this.e.scratch;
+      this._writeLayoutSpec(spec, s);
+      ex.qvp_layout(this.h, s, s + 128);
+      return this._readLayout(s + 128);
+    }
+    /** read a QvpLayout the engine has written at `o`, and everything that goes with it */
+    _readLayout(o) {
+      const ex = this.e.ex; let d = this.e.dv();
       const n = d.getUint32(o + 24, true), lp = d.getUint32(o + 28, true);
       const f = new Float32Array(this.e.mem.buffer.slice(lp, lp + n * 12));
       const lineDy = new Float32Array(n), slots = new Array(n);
       for (let i = 0; i < n; i++) { lineDy[i] = f[i * 3]; slots[i] = [f[i * 3 + 1], f[i * 3 + 2]]; }
-      return (this.currentLayout = { scale: d.getFloat32(o, true), ox: d.getFloat32(o + 4, true), oy: d.getFloat32(o + 8, true), contentW: d.getFloat32(o + 12, true), contentH: d.getFloat32(o + 16, true), pitch: d.getFloat32(o + 20, true), lineDy, slots });
+      const reflowed = d.getUint32(o + 44, true) === 1, rows = d.getUint32(o + 48, true);
+      const L = { scale: d.getFloat32(o, true), offsetX: d.getFloat32(o + 4, true), offsetY: d.getFloat32(o + 8, true), contentW: d.getFloat32(o + 12, true), contentH: d.getFloat32(o + 16, true), lineSpacing: d.getFloat32(o + 20, true), lineDy, slots,
+        fitScale: d.getFloat32(o + 32, true), fitX: d.getFloat32(o + 36, true), fitY: d.getFloat32(o + 40, true), reflowed, rows };
+      // where each group of paths sits: {dx, dy, k} triples, and the group of every path
+      const ng = ex.qvp_layout_groups(this.h, 0, 0);
+      const gp = this.e.buf(ng * 16);
+      ex.qvp_layout_groups(this.h, gp, ng);
+      L.groups = new Float32Array(this.e.mem.buffer.slice(gp, gp + ng * 16));
+      const np = ex.qvp_layout_path_groups(this.h, 0, 0);
+      if (np) { const pp = this.e.buf(np * 4); ex.qvp_layout_path_groups(this.h, pp, np); L.pathGroup = new Uint32Array(this.e.mem.buffer.slice(pp, pp + np * 4)); }
+      else L.pathGroup = null;
+      // paths this layout leaves undrawn: sheet furniture and a native surah frame hidden by the spec or reflow
+      const no = ex.qvp_layout_omitted_paths(this.h, 0, 0);
+      if (no) { const op = this.e.buf(no * 4); ex.qvp_layout_omitted_paths(this.h, op, no); L.omitted = new Set(new Uint32Array(this.e.mem.buffer, op, no)); }
+      else L.omitted = null;
+      // paths drawn a second time elsewhere: a sajdah line whose words ended up on two rows
+      const nr = ex.qvp_layout_repeats(this.h, 0, 0);
+      L.repeats = [];
+      if (nr) {
+        const rp = this.e.buf(nr * 24); ex.qvp_layout_repeats(this.h, rp, nr);
+        const f = new Float32Array(this.e.mem.buffer.slice(rp, rp + nr * 24));
+        for (let i = 0; i < nr; i++) L.repeats.push({ firstPath: f[i * 6], nPaths: f[i * 6 + 1], dx: f[i * 6 + 2], dy: f[i * 6 + 3], kx: f[i * 6 + 4], ky: f[i * 6 + 5] });
+      }
+      return (this.currentLayout = L);
+    }
+    // ── the reader's zoom control ──
+    /** where the zoom control stands: {mode, step, zoom}. All zero is what a page opens on:
+     * stepped, on the printed page. */
+    _putZoom(z, at) { const d = this.e.dv(); d.setUint32(at, ZOOM_MODE[z && z.mode] ?? 0, true); d.setUint32(at + 4, (z && z.step) || 0, true); d.setFloat32(at + 8, (z && z.zoom) || 1, true); return at; }
+    _getZoom(at) { const d = this.e.dv(); return { mode: ZOOM_MODE_NAME[d.getUint32(at, true)] || 'stepped', step: d.getUint32(at + 4, true), zoom: d.getFloat32(at + 8, true) }; }
+    _getZoomChange(at) { return { zoom: this._getZoom(at), view: this.e._getView(at + 12), relaid: !!this.e.dv().getUint32(at + 24, true) }; }
+    /** the same control under another policy, keeping the size the reader is at */
+    zoomMode(spec, zoom, mode) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      this.e.ex.qvp_zoom_mode(this.h, s, z, ZOOM_MODE[mode] ?? 0, this.e.scratch);
+      return this._getZoom(this.e.scratch);
+    }
+    /** one frame of a pinch: `factor` is the fingers' distance against their distance when
+     * they went down, and (x, y) the point between them. Returns {zoom, view, relaid}. */
+    zoomPinch(spec, zoom, view, factor, x, y) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      const v = this.e._putView(view, this.e.scratch2 + 42000);
+      this.e.ex.qvp_zoom_pinch(this.h, s, z, v, factor, x, y, this.e.scratch);
+      const c = this._getZoomChange(this.e.scratch);
+      // the engine laid the page out inside the call: keep the cached layout with it
+      if (c.relaid) this.layoutCurrent();
+      return c;
+    }
+    /** the control moved straight to a step: a size button, a double tap, a reset. Step 0 is
+     * the printed page. */
+    zoomToStep(spec, zoom, step, view) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      const v = this.e._putView(view, this.e.scratch2 + 42000);
+      this.e.ex.qvp_zoom_to_step(this.h, s, z, step, v, this.e.scratch);
+      const c = this._getZoomChange(this.e.scratch);
+      if (c.relaid) this.layoutCurrent();
+      return c;
     }
-    wordBoxView(i) { this.e.ex.qvp_word_box_view(this.h, i, this.e.scratch); const f = new Float32Array(this.e.mem.buffer, this.e.scratch, 4); return { x0: f[0], y0: f[1], x1: f[2], y1: f[3] }; }
+    /** `spec` with this control's zoom in it: what the host lays out and draws with */
+    zoomSpec(spec, zoom) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      this.e.ex.qvp_zoom_spec(this.h, s, z, this.e.scratch);
+      const at = this.e.scratch + 48;
+      const v = this.e.dv().getFloat32(at, true);
+      return { ...spec, reflow: v > 0 ? { ...(spec.reflow || {}), zoom: v } : null };
+    }
+    /** The same control on this page: what the reader was reading at, carried onto the page they
+     * turned to. A step carries as a step, because every page's steps are its own; a free zoom
+     * carries as a size, held inside what this page can reach. */
+    zoomCarried(spec, zoom) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      this.e.ex.qvp_zoom_carried(this.h, s, z, this.e.scratch);
+      return this._getZoom(this.e.scratch);
+    }
+    /** the reflow zoom one step of this page's control means; step 0 is the printed page */
+    zoomAtStep(spec, step) {
+      const s = this.e.scratch2 + 40960; this._writeLayoutSpec(spec, s);
+      return this.e.ex.qvp_zoom_at_step(this.h, s, step);
+    }
+    /** true once the reader has zoomed in, by either road: a magnified view, or a page reflowed
+     * above the printed size. `fitScale` is the scale the page is fitted at (0 = it is at it). */
+    zoomIsZoomed(zoom, view, fitScale = 0) {
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      const v = this.e._putView(view, this.e.scratch2 + 42000);
+      return !!this.e.ex.qvp_zoom_is_zoomed(z, v, fitScale);
+    }
+    /** what a sideways drag on this page means: 'pan' it, or 'turnPage' */
+    sidewaysDrag(zoom, view, fitScale = 0) {
+      const z = this._putZoom(zoom, this.e.scratch2 + 41984);
+      const v = this.e._putView(view, this.e.scratch2 + 42000);
+      return this.e.ex.qvp_sideways_drag(this.h, z, v, fitScale) === 1 ? 'turnPage' : 'pan';
+    }
+    /** The layout the page already has, without computing one: what to read after a call that
+     * laid the page out itself, as the zoom control does. */
+    layoutCurrent() {
+      const s = this.e.scratch;
+      if (!this.e.ex.qvp_layout_current(this.h, s + 128)) return this.currentLayout;
+      return this._readLayout(s + 128);
+    }
+    /** Everything the current layout draws, in drawing order: `{path, placement}` pairs into
+     * `layoutPlacements()`. Omitted paths are already gone and a repeated one is already there
+     * twice, so one loop draws any page — printed or reflowed. */
+    layoutDrawList(bandTop = 0, bandBottom = 0) {
+      const n = this.e.ex.qvp_layout_draw_list(this.h, bandTop, bandBottom, 0, 0);
+      if (!n) return new Uint32Array(0);
+      const p = this.e.buf(n * 8); this.e.ex.qvp_layout_draw_list(this.h, bandTop, bandBottom, p, n);
+      return new Uint32Array(this.e.mem.buffer.slice(p, p + n * 8));
+    }
+    /** what a draw list's `placement` indexes: every group, then every repeat */
+    layoutPlacements() {
+      const n = this.e.ex.qvp_layout_placements(this.h, 0, 0);
+      if (!n) return new Float32Array(0);
+      const p = this.e.buf(n * 16); this.e.ex.qvp_layout_placements(this.h, p, n);
+      return new Float32Array(this.e.mem.buffer.slice(p, p + n * 16));
+    }
+    /** the largest reflow zoom at which every word of this page still fits a row */
+    reflowMaxZoom(spec) { const s = this.e.scratch; this._writeLayoutSpec(spec, s); return this.e.ex.qvp_reflow_max_zoom(this.h, s); }
+    /** the zoom each step of a reader's zoom control lands on for this page, rising */
+    zoomLevels(spec, nominals, band) {
+      const s = this.e.scratch; this._writeLayoutSpec(spec, s);
+      const k = nominals ? nominals.length : 0;
+      const np = k ? this.e.buf(k * 4) : 0;
+      if (k) new Float32Array(this.e.mem.buffer, np, k).set(nominals);
+      const out = this.e.buf(8 * 4);
+      const n = this.e.ex.qvp_zoom_levels(this.h, s, np, k, band || 0, out, 8);
+      return Array.from(new Float32Array(this.e.mem.buffer, out, n));
+    }
+    /** the zoom steps this page ships with, lowest first; zoom 1 is the step before them */
+    zoomSteps(spec) {
+      const s = this.e.scratch; this._writeLayoutSpec(spec, s);
+      const out = this.e.buf(8 * 4);
+      const n = this.e.ex.qvp_zoom_steps(this.h, s, out, 8);
+      return Array.from(new Float32Array(this.e.mem.buffer, out, n));
+    }
+    /** every zoom the search weighs for one step of a zoom control, with its cost */
+    zoomLevelCandidates(spec, nominal, band, floor) {
+      const s = this.e.scratch; this._writeLayoutSpec(spec, s);
+      // one block, two halves: `buf` hands back the same scratch every time
+      const N = 64, z = this.e.buf(N * 8), c = z + N * 4;
+      const n = this.e.ex.qvp_zoom_level_candidates(this.h, s, nominal, band || 0, floor || 0, z, c, N);
+      const zs = new Float32Array(this.e.mem.buffer, z, n), cs = new Float32Array(this.e.mem.buffer, c, n);
+      return Array.from(zs, (v, i) => ({ zoom: v, cost: cs[i] }));
+    }
+    /** the words of a reflowed row, in reading order */
+    rowWords(row) {
+      const n = this.e.ex.qvp_layout_row_words(this.h, row, 0, 0);
+      if (!n) return [];
+      const p = this.e.buf(n * 4); this.e.ex.qvp_layout_row_words(this.h, row, p, n);
+      return Array.from(new Uint32Array(this.e.mem.buffer, p, n));
+    }
+    /** the row a word landed on in a reflowed layout, or null */
+    wordRow(word) { const r = this.e.ex.qvp_layout_word_row(this.h, word); return r === 0xffffffff ? null : r; }
+    /** the view that puts a point inside a word (nx, ny from 0 to 1) at a place on the screen,
+     * then clamps: how a pinch holds its place when the layout reflows under it */
+    viewAnchor(view, word, nx, ny, toX, toY, viewportW, viewportH) {
+      const i = this.e._putView(view, this.e.scratch2 + 32768);
+      this.e.ex.qvp_view_anchor(this.h, i, word, nx, ny, toX, toY, viewportW, viewportH, this.e.scratch);
+      return this.e._getView(this.e.scratch);
+    }
+    /** where a viewport point lands in the laid-out page, for turning a touch into a hit test */
+    viewToLayout(view, vx, vy) {
+      const i = this.e._putView(view, this.e.scratch2 + 32768);
+      this.e.ex.qvp_view_to_layout(this.h, i, vx, vy, this.e.scratch);
+      const f = new Float32Array(this.e.mem.buffer, this.e.scratch, 2);
+      return { x: f[0], y: f[1] };
+    }
+    wordBoundsView(i) { this.e.ex.qvp_word_bounds_view(this.h, i, this.e.scratch); const f = new Float32Array(this.e.mem.buffer, this.e.scratch, 4); return { x0: f[0], y0: f[1], x1: f[2], y1: f[3] }; }
 
     // ── styles (handles undo exactly) ──
     style(sel, color, { ms = 0, layer = LAYER.BASE } = {}) { return this.e.ex.qvp_style_add(this.h, layer, writeSel(this.e, this.e.scratch2 + 12288, sel), rgba(color), ms); }
     styleTarget(target, color, { ms = 0, layer = LAYER.BASE } = {}) { return this.e.ex.qvp_style_add_target(this.h, layer, this._target(target), rgba(color), ms); }
-    unstyle(handle) { return this.e.ex.qvp_style_remove(this.h, handle); }
-    restyle(handle, color, ms = 0) { return this.e.ex.qvp_style_repaint(this.h, handle, rgba(color), ms); }
-    hide(sel) { return this.e.ex.qvp_hide(this.h, writeSel(this.e, this.e.scratch2 + 12288, sel)); }
+    removeStyle(handle) { return this.e.ex.qvp_style_remove(this.h, handle); }
+    recolorStyle(handle, color, ms = 0) { return this.e.ex.qvp_style_recolor(this.h, handle, rgba(color), ms); }
+    hide(sel) { return this.e.ex.qvp_style_hide(this.h, writeSel(this.e, this.e.scratch2 + 12288, sel)); }
     clearStyles() { this.e.ex.qvp_style_clear(this.h); }
     clearLayer(layer) { this.e.ex.qvp_style_clear_layer(this.h, layer); }
-    setDefaultInk(color) { this._defaultInk = rgba(color); this.e.ex.qvp_style_default(this.h, this._defaultInk); }
+    setDefaultColor(color) { this._defaultInk = rgba(color); this.e.ex.qvp_style_default_color(this.h, this._defaultInk); }
     get defaultInk() { return this._defaultInk; }
     /** {ink, diacritics, dots, waqf, sifr, ayahMark, numeral, headers, marks: {name: colour}, ms} → handle */
     theme(t) {
@@ -348,59 +615,61 @@
     // ── clock & display list ──
     /** advance animations; returns true while something is still moving */
     tick(nowMs) { return !!this.e.ex.qvp_tick(this.h, nowMs); }
-    paint() { const p = this.e.ex.qvp_paint(this.h); return new Uint32Array(this.e.mem.buffer.slice(p, p + this.nPaths * 4)); }
-    styled() {
-      const ex = this.e.ex; const n = ex.qvp_styled(this.h, 0, 0); if (!n) return [];
-      const buf = ex.qvp_alloc(n * 8); ex.qvp_styled(this.h, buf, n);
+    colors() { const p = this.e.ex.qvp_colors(this.h); return new Uint32Array(this.e.mem.buffer.slice(p, p + this.nPaths * 4)); }
+    styledPaths() {
+      const ex = this.e.ex; const n = ex.qvp_styled_paths(this.h, 0, 0); if (!n) return [];
+      const buf = ex.qvp_alloc(n * 8); ex.qvp_styled_paths(this.h, buf, n);
       const v = new Uint32Array(this.e.mem.buffer.slice(buf, buf + n * 8)); ex.qvp_dealloc(buf, n * 8);
       const out = new Array(n); for (let i = 0; i < n; i++) out[i] = [v[i * 2], v[i * 2 + 1]]; return out;
     }
     colorOf(i) { return this.e.ex.qvp_color_of(this.h, i) >>> 0; }
 
     // ── highlights ──
-    /** style: {mode:'ink'|'band'|'both', height:'pitch'|'ink', ink, band, padX, padY, radius, seam, ms, layer} */
-    highlight(target, style = {}) { return this.e.ex.qvp_highlight(this.h, this._target(target), writeHl(this.e, this.e.scratch2 + 24576, style)); }
-    rehighlight(handle, target) { return !!this.e.ex.qvp_rehighlight(this.h, handle, this._target(target)); }
-    restyleHighlight(handle, style) { return !!this.e.ex.qvp_restyle_highlight(this.h, handle, writeHl(this.e, this.e.scratch2 + 24576, style)); }
-    unhighlight(handle) { return !!this.e.ex.qvp_unhighlight(this.h, handle); }
-    clearHighlights() { this.e.ex.qvp_clear_highlights(this.h); }
+    /** style: {mode:'ink'|'band'|'both', height:'lineSpacing'|'ink', ink, band, padX, padY, radius, seam, ms, layer} */
+    highlight(target, style = {}) { return this.e.ex.qvp_highlight_add(this.h, this._target(target), writeHl(this.e, this.e.scratch2 + 24576, style)); }
+    moveHighlight(handle, target) { return !!this.e.ex.qvp_highlight_move(this.h, handle, this._target(target)); }
+    restyleHighlight(handle, style) { return !!this.e.ex.qvp_highlight_restyle(this.h, handle, writeHl(this.e, this.e.scratch2 + 24576, style)); }
+    removeHighlight(handle) { return !!this.e.ex.qvp_highlight_remove(this.h, handle); }
+    clearHighlights() { this.e.ex.qvp_highlight_clear(this.h); }
     highlightHandles() { const n = this.e.ex.qvp_highlight_handles(this.h, this.e.scratch, 1024); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 1024))); }
     highlightWords(h) { const n = this.e.ex.qvp_highlight_words(this.h, h, this.e.scratch, 4096); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 4096))); }
     /** animated band boxes in viewport px; draw each id as one nonzero path behind the ink */
-    highlightBoxes() { const n = this.e.ex.qvp_highlight_boxes(this.h, this.e.scratch, 1024); return readBoxes(this.e, this.e.scratch, Math.min(n, 1024)); }
-    bandBoxes(words, { height = 'pitch', padX = 1.2, padY = 0 } = {}) { const p = this.e.putU32(Uint32Array.from(words)); const n = this.e.ex.qvp_band_boxes(this.h, p, words.length, height === 'ink' ? 1 : 0, padX, padY, this.e.scratch, 64); return readBoxes(this.e, this.e.scratch, Math.min(n, 64)); }
+    highlightBoxesView() { const n = this.e.ex.qvp_highlight_boxes_view(this.h, this.e.scratch, 1024); return readBoxes(this.e, this.e.scratch, Math.min(n, 1024)); }
+    wordBands(words, { height = 'lineSpacing', padX = DEFAULTS.HIGHLIGHT_PAD_X, padY = DEFAULTS.HIGHLIGHT_PAD_Y } = {}) { const p = this.e.putU32(Uint32Array.from(words)); const n = this.e.ex.qvp_word_bands(this.h, p, words.length, height === 'ink' ? 1 : 0, padX, padY, this.e.scratch, 64); return readBoxes(this.e, this.e.scratch, Math.min(n, 64)); }
 
     // ── selection ──
     select(anchor, focus = anchor) { this.e.ex.qvp_select(this.h, anchor < 0 ? NONE : anchor, focus < 0 ? NONE : focus); }
     clearSelection() { this.e.ex.qvp_select(this.h, NONE, NONE); }
     selection() { const n = this.e.ex.qvp_selection(this.h, this.e.scratch, 4096); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 4096))); }
-    selectionText(form = 'rasm_uthmani', citation = false) { this.e.ex.qvp_selection_text(this.h, FORM[form] ?? 0, citation ? 1 : 0, this.e.scratch); return this.e.qstr(this.e.scratch); }
+    selectionText(form = 'rasm_uthmani', includeCitation = false) { this.e.ex.qvp_selection_text(this.h, FORM[form] ?? 0, includeCitation ? 1 : 0, this.e.scratch); return this.e.qstr(this.e.scratch); }
 
     // ── memorisation ──
     mask(target, mode = 'hide') { this.e.ex.qvp_mask(this.h, this._target(target), { hide: 0, block: 1, blur: 2 }[mode] ?? 0); }
     maskFrom(i, mode = 'hide') { this.e.ex.qvp_mask_from(this.h, i, { hide: 0, block: 1, blur: 2 }[mode] ?? 0); }
-    maskOptions({ blockColor = '#d9d4c8', padX = 0.6, padY = 0.6, radius = 0.8, reverse = false } = {}) { this.e.ex.qvp_mask_options(this.h, rgba(blockColor), padX, padY, radius, reverse ? 1 : 0); }
-    revealNext(n = 1) { return this.e.ex.qvp_reveal_next(this.h, n); }
-    hideBack(n = 1) { return this.e.ex.qvp_hide_back(this.h, n); }
-    revealWord(i) { return !!this.e.ex.qvp_reveal_word(this.h, i); }
-    hideWord(i) { return !!this.e.ex.qvp_hide_word(this.h, i); }
-    revealAll() { this.e.ex.qvp_reveal_all(this.h); }
-    hideAll() { this.e.ex.qvp_hide_all(this.h); }
+    maskOptions({ blockColor = DEFAULTS.MASK_BLOCK, padX = DEFAULTS.MASK_PAD, padY = DEFAULTS.MASK_PAD, radius = DEFAULTS.MASK_RADIUS, reverse = false } = {}) { this.e.ex.qvp_mask_options(this.h, rgba(blockColor), padX, padY, radius, reverse ? 1 : 0); }
+    unmaskNext(n = 1) { return this.e.ex.qvp_unmask_next(this.h, n); }
+    maskBack(n = 1) { return this.e.ex.qvp_mask_back(this.h, n); }
+    unmaskWord(i) { return !!this.e.ex.qvp_unmask_word(this.h, i); }
+    maskWord(i) { return !!this.e.ex.qvp_mask_word(this.h, i); }
+    unmaskAll() { this.e.ex.qvp_unmask_all(this.h); }
+    maskAll() { this.e.ex.qvp_mask_all(this.h); }
     unmask() { this.e.ex.qvp_unmask(this.h); }
     maskHidden() { const n = this.e.ex.qvp_mask_hidden(this.h, this.e.scratch, 4096); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 4096))); }
     maskWords() { const n = this.e.ex.qvp_mask_words(this.h, this.e.scratch, 4096); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 4096))); }
-    maskBoxes() { const n = this.e.ex.qvp_mask_boxes(this.h, this.e.scratch, 1024); return readBoxes(this.e, this.e.scratch, Math.min(n, 1024)); }
+    /** band boxes for a word list in viewport px through the current layout */
+    wordBandsView(words, { height = 'lineSpacing', padX = DEFAULTS.HIGHLIGHT_PAD_X, padY = DEFAULTS.HIGHLIGHT_PAD_Y } = {}) { const p = this.e.putU32(Uint32Array.from(words)); const n = this.e.ex.qvp_word_bands_view(this.h, p, words.length, height === 'ink' ? 1 : 0, padX, padY, this.e.scratch, 64); return readBoxes(this.e, this.e.scratch, Math.min(n, 64)); }
+    maskBoxesView() { const n = this.e.ex.qvp_mask_boxes_view(this.h, this.e.scratch, 1024); return readBoxes(this.e, this.e.scratch, Math.min(n, 1024)); }
     /** greyed page with a lit window: {lit, byAyah, grey, ink, ayahMarks, ms} → steps */
-    revealStart({ lit = 1, byAyah = false, grey = '#c9c4b8', ink = '#231f20', ayahMarks = true, ms = 0 } = {}) { return this.e.ex.qvp_reveal_start(this.h, lit, byAyah ? 1 : 0, rgba(grey), rgba(ink), ayahMarks ? 1 : 0, ms); }
+    revealStart({ lit = DEFAULTS.REVEAL_LIT, byAyah = false, grey = DEFAULTS.REVEAL_GREY, ink = DEFAULTS.INK, ayahMarks = true, ms = 0 } = {}) { return this.e.ex.qvp_reveal_start(this.h, lit, byAyah ? 1 : 0, rgba(grey), rgba(ink), ayahMarks ? 1 : 0, ms); }
     revealGoto(at) { return !!this.e.ex.qvp_reveal_goto(this.h, BigInt(at)); }
-    revealAt() { const v = Number(this.e.ex.qvp_reveal_at(this.h)); return v === -2 ? null : v; }
-    revealSteps() { return this.e.ex.qvp_reveal_steps(this.h); }
+    revealPosition() { const v = Number(this.e.ex.qvp_reveal_position(this.h)); return v === -2 ? null : v; }
+    revealStepCount() { return this.e.ex.qvp_reveal_step_count(this.h); }
     revealStepOf(i) { return Number(this.e.ex.qvp_reveal_step_of(this.h, i)); }
     revealStop() { this.e.ex.qvp_reveal_stop(this.h); }
 
     // ── crop ──
-    cropBox(target, { pad = 2, keepAyahMarks = true } = {}) { if (!this.e.ex.qvp_crop_box(this.h, this._target(target), pad, keepAyahMarks ? 1 : 0, this.e.scratch)) return null; const d = this.e.dv(), s = this.e.scratch; return { x0: d.getFloat32(s, true), y0: d.getFloat32(s + 4, true), x1: d.getFloat32(s + 8, true), y1: d.getFloat32(s + 12, true), nWords: d.getUint32(s + 16, true), ayahMarkDeco: d.getUint32(s + 20, true) }; }
-    cropSvg(target, { pad = 2, keepAyahMarks = true, background = null } = {}) { if (!this.e.ex.qvp_crop_svg(this.h, this._target(target), pad, keepAyahMarks ? 1 : 0, background ? rgba(background) : 0, this.e.scratch)) return null; return this.e.qstr(this.e.scratch); }
+    cropBounds(target, { pad = DEFAULTS.CROP_PAD, keepAyahMarks = true } = {}) { if (!this.e.ex.qvp_crop_bounds(this.h, this._target(target), pad, keepAyahMarks ? 1 : 0, this.e.scratch)) return null; const d = this.e.dv(), s = this.e.scratch; return { x0: d.getFloat32(s, true), y0: d.getFloat32(s + 4, true), x1: d.getFloat32(s + 8, true), y1: d.getFloat32(s + 12, true), nWords: d.getUint32(s + 16, true), ayahMarkDecoration: d.getUint32(s + 20, true) }; }
+    cropSvg(target, { pad = DEFAULTS.CROP_PAD, keepAyahMarks = true, background = null } = {}) { if (!this.e.ex.qvp_crop_svg(this.h, this._target(target), pad, keepAyahMarks ? 1 : 0, background ? rgba(background) : 0, this.e.scratch)) return null; return this.e.qstr(this.e.scratch); }
   }
 
   class QvpAtlas {
@@ -408,18 +677,22 @@
     free() { this.e.ex.qvp_atlas_free(this.h); this.h = 0; }
     pageOf(surah, ayah) { const p = this.e.ex.qvp_atlas_page_of(this.h, surah, ayah); return p < 0 ? null : p; }
     pageRange(page) { if (!this.e.ex.qvp_atlas_page_range(this.h, page, this.e.scratch)) return null; const v = new Uint16Array(this.e.mem.buffer, this.e.scratch, 4); return { first: [v[0], v[1]], last: [v[2], v[3]] }; }
-    _surah(s) { const d = this.e.dv(); return { n: d.getUint16(s, true), page: d.getUint16(s + 2, true), ayahCount: d.getUint16(s + 4, true), place: ['makkah', 'madinah'][d.getUint8(s + 6)] || '', arabic: this.e.qstr(s + 8), latin: this.e.qstr(s + 16), english: this.e.qstr(s + 24) }; }
+    _surah(s) { const d = this.e.dv(); return { number: d.getUint16(s, true), page: d.getUint16(s + 2, true), ayahCount: d.getUint16(s + 4, true), place: names('place')[d.getUint8(s + 6)] || '', arabic: this.e.qstr(s + 8), latin: this.e.qstr(s + 16), english: this.e.qstr(s + 24) }; }
     surah(n) { return this.e.ex.qvp_atlas_surah(this.h, n, this.e.scratch) ? this._surah(this.e.scratch) : null; }
-    surahs() { const n = this.e.ex.qvp_atlas_surahs(this.h), out = []; for (let i = 0; i < n; i++) { this.e.ex.qvp_atlas_surah_at(this.h, i, this.e.scratch); out.push(this._surah(this.e.scratch)); } return out; }
+    surahs() { const n = this.e.ex.qvp_atlas_surah_count(this.h), out = []; for (let i = 0; i < n; i++) { this.e.ex.qvp_atlas_surah_at(this.h, i, this.e.scratch); out.push(this._surah(this.e.scratch)); } return out; }
     pageOfSurah(n) { const s = this.surah(n); return s ? s.page : null; }
+    /** How many pages the atlas covers. */
+    pageCount() { return this.e.ex.qvp_atlas_page_count(this.h); }
+    /** The whole atlas as JSON text. */
+    json() { this.e.ex.qvp_atlas_json(this.h, this.e.scratch); return this.e.qstr(this.e.scratch); }
     division(kind, n) { if (!this.e.ex.qvp_atlas_division(this.h, { juz: 0, hizb: 1, nisf: 2, rubu_al_hizb: 3 }[kind], n, this.e.scratch)) return null; const v = new Uint16Array(this.e.mem.buffer, this.e.scratch, 4); return { rubuAlHizb: v[0], surah: v[1], ayah: v[2], page: v[3], ayahKey: `${v[1]}:${v[2]}` }; }
     juz(n) { return this.division('juz', n); }
     hizb(n) { return this.division('hizb', n); }
     rubuAlHizb(n) { return this.division('rubu_al_hizb', n); }
-    divisionAt(kind, surah, ayah) { const v = this.e.ex.qvp_atlas_division_at(this.h, { juz: 0, hizb: 1, nisf: 2, rubu_al_hizb: 3 }[kind], surah, ayah); return v < 0 ? null : v; }
-    juzAt(surah, ayah) { return this.divisionAt('juz', surah, ayah); }
+    divisionOf(kind, surah, ayah) { const v = this.e.ex.qvp_atlas_division_of(this.h, { juz: 0, hizb: 1, nisf: 2, rubu_al_hizb: 3 }[kind], surah, ayah); return v < 0 ? null : v; }
+    juzOf(surah, ayah) { return this.divisionOf('juz', surah, ayah); }
     pagesOfJuz(n) { if (!this.e.ex.qvp_atlas_pages_of_juz(this.h, n, this.e.scratch)) return null; const v = new Uint16Array(this.e.mem.buffer, this.e.scratch, 2); return [v[0], v[1]]; }
-    findSurah(text) { const [p, n] = this.e.putStr(text); const c = this.e.ex.qvp_atlas_find_surah(this.h, p, n, this.e.scratch, 128); return Array.from(new Uint16Array(this.e.mem.buffer, this.e.scratch, Math.min(c, 128))).map(k => this.surah(k)); }
+    searchSurahs(text) { const [p, n] = this.e.putStr(text); const c = this.e.ex.qvp_atlas_search_surahs(this.h, p, n, this.e.scratch, 128); return Array.from(new Uint16Array(this.e.mem.buffer, this.e.scratch, Math.min(c, 128))).map(k => this.surah(k)); }
   }
 
   /**
@@ -430,16 +703,35 @@
     constructor(canvas) {
       this.canvas = canvas; this.ctx = canvas.getContext('2d');
       this.base = document.createElement('canvas'); this.baseKey = '';
+      // the engine's draw list for the band in hand, kept until the band moves
+      this.list = null; this.places = null; this.listKey = '';
+      /// How much ink to keep ready at once: a page that fits is drawn once and scrolling never
+      /// draws again. About 17 MB for a page of this mushaf at the first zoom step.
+      this.inkBudget = 64 << 20;
       this.stats = { baseMs: 0, overlayMs: 0, basePaths: 0, overlayPaths: 0, bands: 0 };
     }
-    lineTransform(page, view, line, dpr) {
-      const L = page.currentLayout || { scale: 1, ox: 0, oy: 0, lineDy: null };
-      const s = dpr * view.scale * L.scale, dy = L.lineDy ? L.lineDy[line] : 0;
-      return [s, dpr * (view.ox + view.scale * L.ox), dpr * (view.oy + view.scale * (L.oy + dy * L.scale))];
+    /** transform of one group of paths: a point p is drawn at (kx·p.x + dx, ky·p.y + dy), page units */
+    groupTransform(page, view, group, dpr) {
+      const L = page.currentLayout || { scale: 1, offsetX: 0, offsetY: 0, lineDy: null, groups: null };
+      let dx = 0, dy = 0, kx = 1, ky = 1;
+      if (L.groups && L.groups.length > group * 4) { dx = L.groups[group * 4]; dy = L.groups[group * 4 + 1]; kx = L.groups[group * 4 + 2]; ky = L.groups[group * 4 + 3]; }
+      else if (L.lineDy) dy = L.lineDy[group] || 0;
+      return this.placementTransform(page, view, { dx, dy, kx, ky }, dpr);
     }
+    /** transform of one placement: [a, d, tx, ty] for setTransform(a, 0, 0, d, tx, ty) */
+    placementTransform(page, view, p, dpr) {
+      const L = page.currentLayout || { scale: 1, offsetX: 0, offsetY: 0 };
+      const s = dpr * view.scale * L.scale;
+      return [s * p.kx, s * p.ky, dpr * (view.offsetX + view.scale * (L.offsetX + p.dx * L.scale)), dpr * (view.offsetY + view.scale * (L.offsetY + p.dy * L.scale))];
+    }
+    lineTransform(page, view, line, dpr) { const [a, , tx, ty] = this.groupTransform(page, view, line, dpr); return [a, tx, ty]; }
+    /** put a context into one group's space, so a host overlay lands where the group is drawn */
+    setGroupTransform(c, page, view, group, dpr) { const [a, d, tx, ty] = this.groupTransform(page, view, group, dpr); c.setTransform(a, 0, 0, d, tx, ty); }
+    /** the group a path is drawn with: its reflow group, or its printed line */
+    pathGroup(page, i) { const L = page.currentLayout; return L && L.pathGroup ? L.pathGroup[i] : page.pathLine(i); }
     /** boxes are in layout viewport px; view adds pan/zoom on top */
     drawBoxes(c, boxes, view, dpr) {
-      c.setTransform(dpr * view.scale, 0, 0, dpr * view.scale, dpr * view.ox, dpr * view.oy);
+      c.setTransform(dpr * view.scale, 0, 0, dpr * view.scale, dpr * view.offsetX, dpr * view.offsetY);
       let cur = null, col = 0;
       const flush = () => { if (cur) { c.fillStyle = css(col); c.fill(cur, 'nonzero'); cur = null; } };
       for (const b of boxes) {
@@ -450,22 +742,54 @@
     }
     draw(page, view, dpr) {
       const paths = page.buildPaths();
-      const styled = page.styled();
+      const styled = page.styledPaths();
       const styledSet = new Set(styled.map(s => s[0]));
-      const L = page.currentLayout || { scale: 1, ox: 0, oy: 0, lineDy: null, pitch: 0 };
+      const L = page.currentLayout || { scale: 1, offsetX: 0, offsetY: 0, lineDy: null, lineSpacing: 0 };
       const ink = page.defaultInk;
-      const key = `${view.scale.toFixed(4)}|${view.ox.toFixed(1)}|${view.oy.toFixed(1)}|${dpr}|${ink}|${L.scale}|${L.pitch}|${L.lineDy ? L.lineDy[0] : ''}|${[...styledSet].sort((a, b) => a - b).join(',')}`;
       const W = this.canvas.width, H = this.canvas.height;
-      const setTf = (c, line) => { const [s, tx, ty] = this.lineTransform(page, view, line, dpr); c.setTransform(s, 0, 0, s, tx, ty); };
-      if (key !== this.baseKey || this.base.width !== W || this.base.height !== H) {
+      // The cached ink is a band of the page, not the screen, so scrolling inside it is one
+      // blit and nothing is drawn again. A page that is several screens of ink used to redraw
+      // every path on every frame of a drag, because the cache was keyed on where the reader
+      // had scrolled to. The band is rebuilt only when the drag has travelled half a screen.
+      const viewH = H / dpr, slack = viewH / 2, step = viewH / 2;
+      const scale = view.scale || 1;
+      // A page that fits the ink budget is drawn once, the parts past both ends of the screen
+      // included, and then scrolling draws nothing at all. A taller one keeps a band of itself,
+      // two screens tall, redrawn when the reader scrolls out of it.
+      const contentH = (L.contentH || 0) * scale;
+      const whole = contentH > 0 && W * contentH * dpr * 4 <= this.inkBudget && contentH * dpr <= 16384;
+      const bandTop = whole ? 0 : Math.floor((-view.offsetY - slack) / step) * step;   // view px
+      const bandH = whole ? contentH : viewH + 2 * slack;
+      // the ink drawn into the band, in layout px: what the engine is asked for
+      const cullTop = bandTop / scale, cullBottom = (bandTop + bandH) / scale;
+      // the view the band is rendered under: the reader's, less where the band starts
+      const bandView = { ...view, offsetY: -bandTop };
+      const key = `${view.scale.toFixed(4)}|${view.offsetX.toFixed(1)}|${bandTop.toFixed(1)}|${dpr}|${ink}|${L.scale}|${L.lineSpacing}|${L.lineDy ? L.lineDy[0] : ''}|${L.groups ? L.groups.length + ':' + L.groups[1] : ''}|${(L.repeats || []).length}|${L.omitted ? L.omitted.size : 0}|${[...styledSet].sort((a, b) => a - b).join(',')}`;
+      // The engine says what is drawn and where: each path once under its placement, again for
+      // every row a decoration repeats over, and nothing for a path this layout leaves out. It
+      // is asked once per band, not once per frame: a scroll inside the band changes neither.
+      const listKey = `${page.page}|${cullTop.toFixed(1)}|${cullBottom.toFixed(1)}|${L.scale}|${L.rows}|${L.contentH}`;
+      if (listKey !== this.listKey) {
+        this.list = page.layoutDrawList(cullTop, cullBottom);
+        this.places = page.layoutPlacements();
+        this.listKey = listKey;
+      }
+      const list = this.list, places = this.places;
+      const setPlace = (c, g, v = view) => {
+        const [a, d, tx, ty] = this.placementTransform(page, v, { dx: places[g * 4], dy: places[g * 4 + 1], kx: places[g * 4 + 2], ky: places[g * 4 + 3] }, dpr);
+        c.setTransform(a, 0, 0, d, tx, ty);
+      };
+      const baseH = Math.ceil(bandH * dpr);
+      if (key !== this.baseKey || this.base.width !== W || this.base.height !== baseH) {
         const t0 = performance.now();
-        this.base.width = W; this.base.height = H;
+        this.base.width = W; this.base.height = baseH;
         const b = this.base.getContext('2d');
         b.fillStyle = css(ink);
         let n = 0, cur = -1;
-        for (let i = 0; i < page.nPaths; i++) {
+        for (let k = 0; k < list.length; k += 2) {
+          const i = list[k], g = list[k + 1];
           if (styledSet.has(i)) continue;
-          const ln = page.pathLine(i); if (ln !== cur) { setTf(b, ln); cur = ln; }
+          if (g !== cur) { setPlace(b, g, bandView); cur = g; }
           b.fill(paths[i], page.pathEvenOdd(i) ? 'evenodd' : 'nonzero'); n++;
         }
         this.baseKey = key; this.stats.baseMs = performance.now() - t0; this.stats.basePaths = n;
@@ -473,20 +797,23 @@
       const t1 = performance.now();
       const c = this.ctx;
       c.setTransform(1, 0, 0, 1, 0, 0); c.clearRect(0, 0, W, H);
-      const bands = page.highlightBoxes();
+      const bands = page.highlightBoxesView();
       this.drawBoxes(c, bands, view, dpr);
       c.setTransform(1, 0, 0, 1, 0, 0);
-      c.drawImage(this.base, 0, 0);
+      c.drawImage(this.base, 0, Math.round(dpr * (view.offsetY + bandTop)));
+      const colors = new Map(styled);
       let cur = -1;
-      for (const [i, col] of styled) {
-        if ((col & 255) === 0) continue;
-        const ln = page.pathLine(i); if (ln !== cur) { setTf(c, ln); cur = ln; }
+      for (let k = 0; k < list.length; k += 2) {
+        const i = list[k], g = list[k + 1];
+        const col = colors.get(i);
+        if (col === undefined || (col & 255) === 0) continue;
+        if (g !== cur) { setPlace(c, g); cur = g; }
         c.fillStyle = css(col); c.fill(paths[i], page.pathEvenOdd(i) ? 'evenodd' : 'nonzero');
       }
-      this.drawBoxes(c, page.maskBoxes(), view, dpr);
+      this.drawBoxes(c, page.maskBoxesView(), view, dpr);
       this.stats.overlayMs = performance.now() - t1; this.stats.overlayPaths = styled.length; this.stats.bands = bands.length;
     }
   }
 
-  global.QVP = { QvpEngine, QvpPage, QvpAtlas, CanvasRenderer, Sel, T, KIND, FAMILY, CATEGORY, DECO, FORM, LAYER, MARK, MARKS, NONE, css, rgba, parseTarget };
+  global.QVP = { QvpEngine, QvpPage, QvpAtlas, CanvasRenderer, Sel, T, KIND, FAMILY, CATEGORY, DECORATION, FORM, LAYER, NAMES_TABLE, DEFAULTS, NONE, css, rgba, parseTarget };
 })(typeof window !== 'undefined' ? window : globalThis);