@quran.ws/engine 0.1.0 → 0.3.1

package/docs/API.md

@@ -3,8 +3,8 @@
 One engine, one contract. The C ABI in `crates/qvp-ffi/include/qvp.h` is the source of
 truth; every wrapper (`web/qvp.js`, Kotlin, Dart, React Native, Swift) exposes the same
 names in the platform's own casing, so this page documents once and applies everywhere.
-Examples are JavaScript; read `page.hitTestEx(...)` as `page.hitTestEx(...)` in Dart,
-`page.hitTestEx(...)` in Kotlin, `qvp_hit_test_ex(...)` in C.
+Examples are JavaScript; the same call is `page.hitTest(...)` in Dart, Kotlin and Swift
+and `qvp_hit_test(...)` in C.
 
 **Conventions**
 
@@ -12,6 +12,10 @@ Examples are JavaScript; read `page.hitTestEx(...)` as `page.hitTestEx(...)` in
   Wrappers also accept `'#rgb'`, `'#rrggbb'`, `'#rrggbbaa'`.
 - **Page units** are the printed page's viewBox space (345 × 550 for this mushaf, y down).
   Anything named `…View` is in *viewport pixels through the current layout*.
+- **Defaults.** Every default a wrapper applies (ink, highlight colours and padding, gap bias,
+  tap distance, mask and reveal colours, crop padding) is a `QVP_DEFAULT_*` value in `qvp.h`,
+  defined once in the engine (`crates/qvp-core/src/defaults.rs`) and mirrored as `QvpDefaults`
+  in each wrapper; the parity check keeps every copy equal.
 - **Handles.** Every mutating style/highlight call returns a handle; removing the handle
   undoes exactly that call and nothing else. There is a `clear`, but you never need it.
 - **Targets** resolve to a word list: `'page'`, `'2:255'` (ayah), `'2:255:3'` (word),
@@ -21,11 +25,13 @@ Examples are JavaScript; read `page.hitTestEx(...)` as `page.hitTestEx(...)` in
   diacritic of one word*: `Sel.page()`, `Sel.word(i)`, `Sel.ayah(s,a)`, `Sel.line(n)`,
   `Sel.wordBody(i)`, `Sel.wordMarks(i)`, `Sel.wordMark(i, nth)`, `Sel.wordMarkNamed(i, 'fathah', nth)`,
   `Sel.wordPath(i, nth)`, `Sel.path(p)`, `Sel.mark('shaddah')`, `Sel.category('harakah')`,
-  `Sel.family('dots')`, `Sel.kind('mark')`, `Sel.deco('ayah-mark')`, `Sel.decoIdx(d)`.
-- **The engine decides, the host draws.** Hit-testing, layout, styling, highlight bands,
-  masks and search are engine calls. A wrapper only marshals and paints what it is told.
-- **Data is separate from code.** Pages (`NNN.qvp`), the atlas (`atlas.qva`) and the
-  optional text sidecars (`NNN.words.json`) are assets your app loads; no package bundles them.
+  `Sel.family('dots')`, `Sel.kind('mark')`, `Sel.decoration('ayah-mark')`, `Sel.decorationIndex(d)`.
+- **The engine computes, the host renders.** Hit-testing, layout, styling, highlight bands,
+  masks and search are engine calls. A wrapper marshals the calls and renders the results.
+- **Data is separate from code.** Pages (`NNN.qvp`), the atlas (`atlas.qva`), optional text
+  sidecars (`NNN.words.json`) and reusable title-only assets under `surah-names/` are loaded
+  by the app; no package bundles them. Titles are published as individual and combined QVP
+  and SVG files, plus a WOFF2 font and its map.
 
 ## Loading
 
@@ -37,32 +43,40 @@ page.attachWords(await fetchJson('pages/042.words.json'));               // opti
 page.free(); atlas.free();
 ```
 
-`page.width/height/page/nLines/nAyahs/nWords/nPaths/nDecos`, `page.naturalPitch`.
+`page.width/height/page/nLines/nAyahs/nWords/nPaths/nDecorations`, `page.lineSpacing`,
+`page.grid`.
 
 ## Words, ayahs, lines, decorations
 
 | | |
 |---|---|
-| `page.words[i]` | `{idx, surah, ayah, word, line, lineIdx, ayahIdx, x0,y0,x1,y1, text, firstPath, nPaths}` |
-| `page.ayahs[i]` | one **fragment** per printed line: `{surah, ayah, fragment, fragments, flags, rubuAlHizb, firstWord, nWords, ayahMarkDeco, bbox}` |
-| `page.lines[i]` | `{lineNo, isHeader, firstWord, nWords, bbox, bandY0, bandY1, centre}` |
-| `page.decos[i]` | `{kind, surah, ayah, line, bbox, text, firstPath, nPaths}` — ayah marks, surah banners, basmalah, division rosettes, sajdah signs, page furniture |
+| `page.words[i]` | `{index, surah, ayah, word, line, lineIndex, ayahIndex, x0,y0,x1,y1, text, firstPath, nPaths}` |
+| `page.ayahs[i]` | one **fragment** per printed line: `{surah, ayah, fragment, fragments, flags, rubuAlHizb, firstWord, nWords, ayahMarkDecoration, bbox}` |
+| `page.lines[i]` | `{lineNumber, isHeader, firstWord, nWords, bbox, bandY0, bandY1, centre}` |
+| `page.decorations[i]` | `{decoration, surah, ayah, line, bbox, text, firstPath, nPaths}` — ayah marks, surah banners, basmalah, division rosettes, sajdah signs, page furniture |
 | `page.findWord(s,a,w)` | index or −1 |
-| `page.resolve(target)` | word indices in reading order |
+| `page.targetWords(target)` | word indices in reading order |
 | `page.wordForm(i, form)` | `'rasm_uthmani' \| 'rasm_imlai' \| 'qpc' \| 'rasm' \| 'search'` (derived forms need the sidecar; `hasForm(form)`) |
 | `page.attachWords(json)` | attach `NNN.words.json` (`{"s:a:w": {rasm_uthmani, rasm_imlai, qpc, rasm, search}}`); returns words updated |
 | `page.pathKind/Mark/Family/Category(p)`, `pathWord(p)`, `pathLine(p)`, `pathNthMark(p)` | per-path facts from the geometry table |
 
-An ayah is several fragments. `resolve('2:255')` gives all its words on the page;
-`ayahWordCount(s,a)` returns `{count, complete}` — `complete` is false when the ayah
+An ayah is several fragments. `targetWords('2:255')` gives all its words on the page;
+`ayahWordCount(s,a)` returns `{count, isComplete}`; `isComplete` is false when the ayah
 continues on another page.
 
+**Word tokenization.** The mushaf holds **77,432** words, keyed `surah:ayah:word` — the
+quran-ws shared word identity (the same keys quran-svg, quran-svg-elements and the tajweed
+spans use). A host app with its own word table may tokenize an edge case differently (a
+compound written as one word split into two, or the reverse); map at the boundary with
+`findWord(s,a,w)` / `words[i].wordKey`, and treat a per-ayah word-count mismatch as
+"skip, don't guess" — the engine's numbering follows the standard, never a host table.
+
 ## Metadata (no database needed)
 
 `surahs()` → `{number, arabic, latin, english, place, ayahCount, hasBanner, hasBasmalah}`;
 `divisions()` → juz/hizb/nisf/`rubu_al_hizb` that **start** on the page; `rosettes()` (drawn division
 marks); `sajdahs()`; `ayahMarks()` → real ayah medallions with centre/radius and the
-ornament/numeral path indices (swap or restyle them); `ayahKeys()`; `wordLabel(i)`,
+ornament/numeral path indices (swap or recolorStyle them); `ayahKeys()`; `wordLabel(i)`,
 `ayahLabel(i)` for screen readers.
 
 ## Text and search
@@ -70,7 +84,7 @@ ornament/numeral path indices (swap or restyle them); `ayahKeys()`; `wordLabel(i
 ```js
 page.text('2:255')                                   // with the mushaf's own line breaks
 page.text('page', {form: 'search', wordSep: ' '})
-page.search('الرحمان', {mode: 'includes'})            // [{word, wordKey, text, index, loose}]
+page.search('الرحمان', {mode: 'includes'})            // [{word, wordKey, text, index, isLooseMatch}]
 page.citation([12, 13, 14])                           // "2:255" / "2:255-257" / "2:286, 3:1"
 engine.strip(s); engine.fold(s); engine.normalize(s); engine.looseKey(s)
 ```
@@ -82,41 +96,415 @@ Modes: `includes`, `exact`, `prefix`. Without a sidecar it searches the stripped
 ## Hit testing
 
 ```js
-page.hitTestViewEx(vx, vy, {maxDistance: 6, gapBias: 0.6})
-// → {word, path, deco, line, distance, exact, wordKey, ayahKey} | null
+page.hitTestView(viewX, viewY, {maxDistance: 6, gapBias: 0.6})
+// → {word, path, decoration, line, distance, isExact, wordKey, ayahKey} | null
 ```
 
 Exact outline first, then **nearest with direction**: the point is resolved to a line
-by its pitch band, then to a word, with a gap between two words split 60/40 towards the
+by its line spacing band, then to a word, with a gap between two words split 60/40 towards the
 preceding (right-hand) word — trailing ink is drawn *into* the following gap in this
-print. `hitBoxes()` returns the same partition as boxes (no dead zones on a line);
-`lineBands()` the pitch bands. `hitTest`/`hitTestView` are the exact-only variants.
+print. `hitAreas()` returns the same partition as boxes (no dead zones on a line);
+`lineBands()` the line spacing bands. `hitTestExact`/`hitTestExactView` are the exact-only variants.
 
 ## Layout
 
 ```js
 const L = page.layout({viewportW, viewportH, padTop, padBottom, padLeft, padRight,
-                       lineSpacing: 1.0, lineGap: 0, fillHeight: false, nominalLines: 15});
-// L = {scale, ox, oy, contentW, contentH, pitch, lineDy[], slots[]}
+                       lineSpacing: 1.0, fillHeight: false, gridLines: 0,
+                       cropLeft: 0, cropRight: 0, maxAspectSlack: 0, bannerZoom: 0,
+                       surahFrames: true});
+// L = {scale, offsetX, offsetY, contentW, contentH, lineSpacing, lineDy[], slots[], fitScale, fitX, fitY}
+page.layoutLineSpacingToFill(spec)   // the lineSpacing multiplier that fills the padded viewport of spec
+page.layoutWastedFraction(spec)      // the share of the padded viewport left empty at fit-to-width
+page.layoutPrintedHeight(spec)       // the page's height at the printed pitch: contentH before fill-height adds leading
+page.grid                            // {lines, lineSpacing}: the mushaf's line count and the printed spacing
+page.lineSpacing                     // the printed line spacing of this page, in page units
 ```
 
+**The fit.** `fitScale`, `fitX`, `fitY` is the view transform that shows the whole laid-out
+content in the viewport: shrink by `fitScale` when the content is taller than the viewport
+(never enlarge), then centre. A host draws at `fitX + fitScale·viewX`, `fitY + fitScale·viewY`
+and applies its own pan and zoom on top. `maxAspectSlack` bounds the content width to
+`viewportH·pageW/pageH·slack` so a landscape screen does not stretch the lines (0 = no
+bound; the examples use 1.15). `cropLeft`/`cropRight` cut the printed side margins (page
+units) so the ink spans the padded width. Wrappers compute none of this; the engine's
+answers for forty viewport cases are in `conformance/scenarios/layout.json`.
+
+**`bannerZoom` caps how big a surah name or a basmalah gets as the reader zooms in**, as a
+multiple of its PRINTED size. 0 (the default) leaves it uncapped: the drawing grows with the
+words around it until it fills the row, which for a surah name is about five times the print.
+1 holds it at the printed size however far the reader zooms — what a host that draws its own
+frame around the printed name wants, since the frame has a shape to keep. It is a LAYOUT knob
+and not one of the reflow knobs, because the reader's zoom control fills those in itself
+(`page.zoomSpec`), so a host that pinches never gets to set one; only a reflowed page grows a
+banner at all.
+
+**`surahFrames` controls the source-native frame around a surah name.** It defaults to
+`true`, preserving the printed page. Set it to `false` when the host supplies its own frame.
+The native frame is then omitted from drawing and from exact hit testing. Reflowed titles and
+the reusable title assets are frameless either way.
+
+**Drawing your own frame.** `page.surahHeadersView()` gives each heading two boxes in
+viewport px: `x0, y0, x1, y1` is the box a frame fills, the page's text block wide and the
+heading's row tall, and `titleX0 … titleY1` is the title ink inside it. Both leave out a
+native frame, whether the layout draws one or not, so the numbers do not change when the
+reader turns the frame off. `page.surahHeaders()` is the same in page units.
+
+```js
+page.layout({ ...spec, surahFrames: false, bannerZoom: 1 });
+for (const h of page.surahHeadersView()) {
+  ctx.strokeRect(h.x0, h.y0, h.x1 - h.x0, h.y1 - h.y0);   // your frame
+}
+```
+
+`bannerZoom: 1` belongs with this: it holds the title at its printed size as the reader zooms,
+so a frame with a fixed shape still fits it.
+
+Read the boxes from `surahHeadersView()` rather than mapping `decorationInfo` yourself. That
+box is the one stored in the file, so it covers the native frame you just hid, and it is in
+page units: the layout moves a heading's line by `L.lineDy[line]`, and a mapping that leaves
+that term out draws the frame about eight px above the title on a printed page.
+
+**What this is for.** A printed mushaf page is squatter than a phone screen: fitted to the
+width of a tall viewport it leaves a band of empty paper top and bottom. The layout knobs
+exist to fill that empty band with leading, so the lines drift apart until the page fills
+the screen, and for nothing else. They are an expansion control, never a compression one.
+
 Horizontal placement is as printed; each line moves by `lineDy[line]`. Lines are never
-re-spread onto a grid (printed lines are not equally tall or equally pitched, and ink
+re-spread onto a grid (printed lines are not equally tall or equally spaced, and ink
 crosses into neighbouring lines): every line keeps its printed position and the same
-delta is added between each pair of consecutive lines. `lineSpacing` sets that delta as
-a multiple of the printed pitch (`pitch·(lineSpacing−1)`), `lineGap` adds leading in page
-units, `fillHeight` picks the delta that makes the page fill the padded viewport
-(pages 1–2 stay centred). `slots[]` boundaries sit halfway between neighbouring lines.
-Pure helpers:
-`engine.gapToFill(pageW, pageH, lines, viewW, viewH, max)` and `wastedFraction(...)`.
-`wordBoxView(i)` gives a word's box in viewport px for scroll-into-view.
-
-`nominalLines` is the grid the page is laid out *inside*, not the page's own line
-count: it defaults to 15 and is clamped up to `page.nLines`, never down. A short page
-laid out at 15 — al-Fatiha's 7 lines, say — is therefore centred in a full-page box and
-draws at under half the height, with the rest of the viewport left empty. That is the
-spec working, not a rendering bug. Pass `nominalLines: page.nLines` when you want the
-page to fill what you gave it, and keep 15 only when several pages must share one grid.
+delta is added between each pair of consecutive lines. One name covers the concept at
+every level: `page.lineSpacing` is the printed spacing, the spec's `lineSpacing` is the
+multiplier you ask for, `L.lineSpacing` is the spacing the layout produced. The delta is
+`page.lineSpacing·(lineSpacing − 1)`; `fillHeight` picks the delta that makes the page fill
+the padded viewport instead. A short page (fewer lines than the grid, pages 1 and 2) has no
+height of its own to fill, so under `fillHeight` it takes the rows a full page gets,
+`(viewportH − pads)/gridLines` each, centred. Leading only opens up: the printed spacing
+is the floor, and a page that cannot fit at it reports a `contentH` taller than the
+viewport. `slots[]` boundaries sit halfway between neighbouring lines, except beside a
+header line (surah name, basmalah), where they stop half a line spacing from the line's
+centre: the banner on pages 1 and 2 sits several line spacings above the text, and that
+gap is not the first line's.
+
+**Spacing only opens up.** The delta is clamped at 0, so `lineSpacing < 1` or a
+`fillHeight` that would need to tighten lays the page out exactly as printed. Lines can
+never be pulled closer together than the mushaf prints them. The text width is not
+adjustable either: the page is always fitted to the padded viewport width
+(`scale = (viewportW − padLeft − padRight) / pageW`), so the only layout knob a reader gets
+is more leading, never a narrower or wider line.
+
+`gridLines` is the grid the page is laid out inside, not the page's own line count. 0
+means the page's grid (`page.grid.lines`: 15 for this mushaf, or more when a page has
+more), clamped up to `page.nLines`, never down. A short page laid out on 15 lines,
+Fatihah's 7 for instance, is therefore centred in a full-page box: without `fillHeight` it
+draws at under half the height with the rest of the viewport left empty; with it, its lines
+take full-page rows. That is the spec working, not a rendering bug. Pass
+`gridLines: page.nLines` when you want the page to fill what you gave it, and keep the
+default only when several pages must share one grid.
+
+`wordBoundsView(i)` gives a word's box in viewport px for scroll-into-view.
+
+## Reflow
+
+```js
+const L = page.layout({viewportW, viewportH, padLeft, padRight,
+                       reflow: {zoom: 1.6, fill: 'ragged' | 'justified' | 'centred', gaps: 'printed',
+                                wordGap: 1, maxStretch: 1.6}});
+// L.reflowed, L.rows, L.groups (dx, dy, kx, ky per group), L.pathGroup (the group of a path)
+page.reflowMaxZoom(spec)   // the largest zoom whose rows still hold every word of this page
+L.omitted                  // paths this layout does not draw (the sheet's own furniture)
+page.rowWords(row)         // the words of a reflowed row, in reading order
+page.wordRow(word)         // the row a word landed on, or null
+```
+
+Reflow keeps the page width and breaks the words onto rows of that width. A row is the page's
+printed text block, not the whole sheet, so the print's side margins stay. `zoom` is the ink
+size as a multiple of fit-to-width, so a row holds `blockW/zoom` page units and the page grows
+taller than the viewport: `fitScale` stays 1 and the host scrolls `contentH`. Without `reflow`
+the layout above is unchanged.
+
+**Zoom 1 is the printed page.** A `reflow` of `zoom: 1` or less lays the page out as printed:
+`reflowed` is 0, there are no rows, and every knob above — leading, `fillHeight`, the grid a
+short page sits on, the crops, the aspect bound — behaves exactly as it does without `reflow`.
+A reader returning to 1 gets the printed page back, whatever else they have set. Rows appear
+once the ink is bigger than the print, and text flows from one line into the next only once
+the rows are narrower than the printed lines.
+
+The running head (surah name and juz) and the page number are printed outside the page box.
+They belong to the sheet, and a reflowed page has none, so they are left out and their paths
+are listed in `L.omitted` for renderers to skip. A host that wants them draws its own, from
+`page.pageNumber` and the atlas.
+
+What the engine holds to: a word is placed whole and is never reshaped or resized, an ayah
+keeps the medallion that closes it on the same row, a sajdah line travels with its word, a
+surah name or basmalah keeps a row of its own and text never flows across it, and no word
+moves to another page.
+
+**How the rows come out.** `breaks` picks where the words are cut into rows. `greedy` fills
+each row until the next word does not fit, which is what leaves one row full and the next half
+empty when a long word falls at a boundary. `even` weighs every row of a block together and
+takes the cuts that leave them closest in width, costing a row the square of what it is left
+short. `fitted`, the default, weighs a row by the width it can reach once its gaps have opened
+as far as `maxStretch` allows, so a shortfall the spacing can absorb costs little and one it
+cannot moves the cut; it also charges for the step between a row and the row above it, and for
+the spacing spent, which makes a better cut worth more than a wider gap.
+
+Over all 604 pages at zoom 1.3, 1.8 and 2.4, counting every row that does not end a block,
+because a row that ends a block is short only because the text ran out:
+
+| breaks | median fill | standard deviation | rows under 60% | 95th step | worst step |
+|---|---:|---:|---:|---:|---:|
+| greedy | 92.6% | 10.48 pp | 2.40% | 29.1 pp | 87.1 pp |
+| even | 91.3% | 8.71 pp | 1.03% | 21.2 pp | 87.1 pp |
+| fitted | 90.6% | 8.45 pp | 0.92% | 19.5 pp | 64.8 pp |
+
+The step is the difference in fill between a row and the row above it. `fitted` adds 7 rows
+over the whole mushaf and costs 0.05 ms a page on a warm layout: 0.25 ms against 0.20 ms at
+the median, 0.32 ms against 0.27 ms at the 95th percentile.
+
+**The zoom steps a reader gets.** `page.zoomLevels(spec)` returns the zoom each step of a
+reader's zoom control lands on for this page. The rows only rearrange at certain zooms, so a
+zoom that breaks a page well can sit beside one that breaks it badly. The engine searches a
+band around each nominal step and returns the zoom whose rows come out best, counting how
+short the rows are, how much each differs from the row above, how tall the page grows, and how
+far the zoom is from the step asked for. Each returned zoom is at least 8% above the one
+before it. Zoom 1, the printed page, is the step every control starts from and is not
+returned.
+
+Over all 604 pages, against the same three steps taken at their nominal zoom:
+
+| steps | median fill | standard deviation | rows under 60% | 95th step |
+|---|---:|---:|---:|---:|
+| nominal ×1.4, ×1.8, ×2.2 | 91.1% | 7.54 pp | 0.47% | 17.5 pp |
+| searched | 92.4% | 6.79 pp | 0.17% | 15.7 pp |
+
+The zooms chosen for a page differ from its neighbours' by 2.2% to 3.3% at the median and at
+most 12.4%, so the ink changes size a little from page to page. Widening the band finds better
+rows and makes that change larger. The search takes about 40 ms a page. Its answer depends only on the page: the same zooms come
+back at every viewport measured, from 360x1200 to 820x1180, so a generator can work the table
+out once and ship it.
+
+`page.zoomSteps(spec)` reads this page's steps out of the table the engine carries, which is
+what a reader's zoom control uses: the search runs once, at release time, and the engine ships
+the answer. A lookup takes about 0.02 ms against about 40 ms for the search.
+
+The steps were chosen for the whole mushaf at once, weighing a page's own rows against how much
+the ink changes size at the page turn, so no page turn changes the text size by more than 7%
+and half change it by about 1%. They were chosen for the engine's own breaking and spacing: a
+reader who changes a spacing knob keeps these steps and gets a page laid out with the settings
+they asked for, so a spacing knob never resizes the text.
+
+| steps | median fill | standard deviation | rows under 60% | 95th step |
+|---|---:|---:|---:|---:|
+| nominal ×1.4, ×1.8, ×2.2 | 90.5% | 7.49 pp | 0.47% | 17.1 pp |
+| the shipped table | 91.3% | 6.90 pp | 0.21% | 15.8 pp |
+
+`page.zoomLevels(spec, nominals, band)` runs the search itself, and
+`page.zoomLevelCandidates(spec, nominal, band, floor)` returns every zoom it weighs with its
+cost. These are what the generator uses; a reader does not need them.
+
+`cargo run -p qvp-convert --release -- zoom-levels dist/pages crates/qvp-core/src/zoom_table.rs`
+writes the table, and `--check` reports whether the committed one is still what the page data
+and the layout produce. `scripts/check.sh gates` runs the check, and the table carries what it
+was built from, so a change to the artwork or to the spacing defaults is caught rather than
+left to drift.
+
+`fill` is `centred` (the default), `ragged` (the row starts at the right margin) or `justified`
+(gaps stretch to both margins, the row that ends a block excepted). `gaps` is `uniform` (the
+default) or `printed`, and `wordGap` scales whichever it picked.
+
+`relax` opens a row that still comes out short. Each row is opened a share of the way towards
+the widest row within three rows of it, because those are the rows a reader sees beside it and
+compares it with. The window slides, so a row is measured against its own neighbours rather
+than against whichever group of rows it fell in, and it holds a fixed number of rows, so the
+same page is set the same way on any screen. The row is never justified by this, and
+`maxStretch` caps how far a gap may open, as a multiple of the air the page keeps between two
+words. That cap is why a row of few words opens less than a row of many: fewer gaps, less room,
+before the words stand apart. Half way (`relax: 0.5`) is where a page comes out most even —
+past it only the rows with many gaps keep moving, and the page reads less even, not more.
+
+**Words are spaced by the air between their strokes.** Not by the distance between their
+boxes: the calligraphy interlocks one word's opening stroke with the one before it, so the
+boxes of `سَاحِرٌ` and `كَذَّابٌ` overlap by 12 page units while the strokes stay 5 apart. Space
+that pair by its boxes and it comes apart, leaving a hole where the strokes used to interleave.
+
+The engine traces every word's outline into bands counted from its line's baseline
+(`defaults::SLICES_PER_LINE`, 96 of them) and measures the narrowest distance between two words
+over the bands they share: `page.wordsClearance(a, b, dx)`, with
+`page.shiftForClearance(a, b, air)` for the shift that leaves a given air. The outline is
+walked, not its points: a curve's control points stand far apart, so bands between them would
+read as empty and a pair would be measured against ink that is not facing it. The tracing waits
+until a reflow asks for it, because loading a page is otherwise three times faster.
+
+The trace holds a word's marks as well as its letters, because a mark reaching past the letters
+still has to clear the next word, and a band knows the height it reaches at. A medallion is
+traced with the word it closes, so the next word is spaced from the medallion.
+
+The shape decides what a pair may do: a final `م` written round lets the next word tuck under it
+in 83% of pairs, the same letter written with a tail in 47%, and the engine reads that off the
+ink rather than off a list of letters. Across the mushaf the print leaves ink clear of ink in
+6,699 of 6,700 neighbouring pairs, and a reflowed row holds to that: of 37,788 placed pairs the
+only ink that meets is the `ٱلرَّحْمَٰنِ ٱلرَّحِيمِ` the print draws as one piece. A reflowed row leaves every pair the air the print keeps on
+that page, which across the 604 pages holds the placed air to a median of 4.2 page units and a
+spread of 0.5, against a box gap that varies by 2.7.
+
+Marks are not in this measure. A word's box holds them, two words in three carry ink that
+reaches past their letters, and spacing to those would set such pairs tighter than the rest.
+
+**One word drawn inside another.** Strokes almost never meet: 10 of this mushaf's 68,612
+neighbouring pairs. Three of those are `ٱلرَّحْمَٰنِ ٱلرَّحِيمِ`, where `ٱلرَّحِيمِ` is set in the bowl
+of `ٱلرَّحْمَٰنِ`, overlapping by 19 to 26 page units where the next deepest reaches 3.8. Such a
+pair keeps the place the print gave it and justification does not stretch it; only a row break
+between the two sets them as ordinary words. `page.wordsInterlock(a, b)` reports it, and
+`defaults::INTERLOCK_DEPTH` is where the line is drawn.
+
+**Where each mark goes.** What a mark is for decides which word it travels with, and the rows
+then hold to what a reader expects of the page:
+
+- The medallion that closes an ayah runs with that ayah's last word, so no row opens with it.
+  Where the next word shares its row, the medallion is set midway between the two, measured as
+  the air on either side, rather than at the distance the print gave it on a line it is no
+  longer on.
+- A sajdah mark closes the word before it and runs with that word, so no row opens with it
+  either. It is followed by the medallion of its own ayah, and the two are read as one sign, so
+  the engine gives them the same word whatever their geometry says.
+- A rubu_al_hizb opens a division, so it runs with the word it opens and no row closes with it.
+
+A mark printed inside the text block claims its own room on the row and keeps the distance the
+print put between it and its word. In this mushaf every rubu_al_hizb and sajdah mark is printed
+in the text. A mark printed out in the sheet's margin, where a reflowed row has no room, keeps
+the margin and the side the print gives it and follows its word down to the new row.
+The sajdah line is drawn over the words it marks, wherever they now are: when the span breaks
+across rows, the stroke is drawn once per row, stretched along x to cover that row's part of
+the span, and carrying the same shift as those words so it keeps the height above them the
+print gave it. It is the one piece of ink the layout stretches, and only along x. A word is
+always placed with `kx == ky == 1`.
+
+One decoration can hold more than one mark: the sajdah of 16:50 on page 272 is a single
+record holding the stroke over its words *and* the sign printed in the margin. They are placed
+apart — the sign keeps its size and is drawn once, beside the word it stands next to — so a
+path's group follows the job it does, not only the record it belongs to.
+
+**What a renderer draws.** `page.layoutDrawList(bandTop, bandBottom)` is every drawing this
+layout makes, in drawing order: `{path, placement}` pairs into `page.layoutPlacements()`. A
+path the layout leaves out — sheet furniture, or a native surah frame once the page reflows — never appears, a sajdah
+line stroked over the two rows its words landed on appears twice, and a printed page hands back
+each path under its own line. So one loop draws any page, and no host has to know which case it
+is in:
+
+```js
+for (const {path, placement} of drawList) { setTransform(places[placement]); fill(paths[path]); }
+```
+
+The band holds it to a part of the laid-out page, in viewport px, as `L.slots` and every
+`…View` answer are; a band no taller than nothing means the whole page.
+
+A reflowed page is several screens of ink, so a renderer draws it into an image once and lets
+the reader scroll that image, rather than drawing again on every frame. Both reference
+renderers keep the whole page when it fits their ink budget — about 18 MB for a page of this
+muṣḥaf at its largest step on a phone — and fall back to a band two screens tall when it does
+not, which is redrawn only when the reader scrolls out of it. That is what the band argument is
+for. On iOS the image is the content of a `UIScrollView`, so the scroll itself — the
+deceleration, the rubber band at the ends, the indicator — is the platform's own.
+
+`reflowMaxZoom(spec)` is the largest zoom at which every word still fits a row (2.44 on page
+121, whose longest word is 121 of 345 page units). Clamp a pinch to it; past it the engine
+still lays the page out, but ink wider than a row runs past the margin.
+
+**Groups.** A reflowed page shifts words, not lines, so `L.lineDy[line]` no longer places a
+path. `L.groups` holds one `{dx, dy, kx, ky}` per group and `L.pathGroup[i]` the group of path
+`i`: draw the path's points at `(kx·p.x + dx, ky·p.y + dy)` in page units, then apply `scale`
+and the offsets as before. Without reflow there is one group per printed line, `dx` is 0, both
+scales are 1 and `dy` is that line's `lineDy`, so one code path serves both. `slots[]` holds
+the rows. `L.repeats` lists paths to draw a second time (`{firstPath, nPaths, dx, dy, kx,
+ky}`), which is how one sajdah line covers two rows; a renderer draws them after the main
+pass, in the same colour the path already has.
+
+## The reader's pan and zoom
+
+```js
+let view = {scale: 1, offsetX: 0, offsetY: 0};
+view = engine.viewZoomAbout(view, focalX, focalY, factor);   // a pinch, clamped
+view = engine.viewPan(view, dx, dy);                          // a drag
+view = engine.viewClamp(view, L.contentW, L.contentH, viewportW, viewportH);
+view = page.viewAnchor(view, word, nx, ny, toX, toY, viewportW, viewportH);
+const {x, y} = page.viewToLayout(view, touchX, touchY);       // a touch → the laid-out page
+engine.viewSwipe(dx, dy, vx, vy)                              // +1, -1 or 0
+```
+
+A layout places the page's ink; the reader pans and zooms on top of it. That arithmetic is the
+engine's, so the platforms cannot drift apart: a host reads the gesture from its own recognizer
+and asks for the view it produces. `viewZoomAbout` keeps the point under two fingers under
+them, `viewClamp` centres an axis the content does not fill and covers the viewport on one it
+overflows.
+
+`viewAnchor` is the one reflow needs. A relayout moves a word to another row, so a host cannot
+hold the page still by remembering pixels: it remembers the word under the fingers and the
+point inside it (`nx`, `ny` from 0 to 1) and asks for the view that brings that point back to a
+place on the screen. A word that moved rows cannot hold both axes on a page of fixed width —
+its new row decides its x — so the vertical place is the one this keeps.
+
+## The reader's zoom control
+
+```js
+let zoom = {};                                           // stepped, on the printed page
+const c = page.zoomPinch(spec, zoom, view, factor, x, y); // one frame of a pinch
+zoom = c.zoom; view = c.view;                             // c.relaid: the page moved under it
+spec = page.zoomSpec(spec, zoom);                         // the spec to lay out and hit-test with
+page.zoomToStep(spec, zoom, 2, view);                     // a size button, a double tap, a reset
+page.zoomMode(spec, zoom, 'continuous');                  // another policy, same size
+```
+
+A pinch means two different things on a muṣḥaf page. It can scale the printed page, the way it
+scales a photograph, and leave the reader panning across lines that no longer fit. Or it can
+ask for bigger ink at the same page width, which is reflow: fewer words to a row, the rest
+moved down. Which of those it means, where it lands, when it commits and what holds the
+reader's place across the relayout is one policy, and it is the engine's — a host reads the
+gesture from its own recognizer and asks what it produced.
+
+`factor` is the distance between the fingers against their distance when they went down: the
+whole gesture every time, not the change since the last frame. There is no call when the
+fingers lift.
+
+**Three modes.** `stepped` is what a reader gets unless a host says otherwise: the pinch lands
+on one of the page's own steps (`zoomSteps`) and the page breaks its rows again at that size,
+so a reader never ends up at a zoom that breaks the page badly. `continuous` reflows to
+whatever the fingers ask for, between the printed page and `reflowMaxZoom`, quantized to 0.01
+so a pinch never asks for a layout that moves no word. `magnify` scales the laid-out page and
+never changes a row. A zeroed control is `stepped` on the printed page, so a host that sets
+nothing gets the reader's behaviour.
+
+**Where a step commits.** Two neighbouring steps meet at their geometric mean, because a zoom
+is a ratio and not a distance, and the commit is held off by 3% either way so a finger resting
+on the boundary does not flicker between two layouts. The steps are at least 1.08 apart
+(`zoomLevels`), and `1.03² < 1.08`, which is what keeps the two thresholds of one step clear of
+each other. The commit happens mid-gesture, one step per crossing: the reflow is the loud
+event, and a pinch that does nothing until release reads as broken.
+
+**Holding the reader's place.** On every commit the engine hit-tests the point between the
+fingers against the layout in hand, lays the page out at the new size, and anchors that point
+back under them with `viewAnchor`. The word is found again on each commit rather than
+remembered from the start of the gesture: `viewAnchor` can only promise the vertical place, so
+a remembered word slides sideways out from under the fingers while the word found now is the
+one they are on. The host never sees the word.
+
+The control owns one field of the spec and leaves the reader's spacing knobs alone, so
+`zoomSpec` is what a host lays out, draws and hit-tests with. `zoomPinch` and `zoomToStep` lay
+the page out themselves when they commit, and the wrapper reads that layout back — a host does
+not lay out again after `relaid`.
+
+## Where geometry is answered
+
+Every call named `…View` answers in viewport pixels through the current layout:
+`wordBoundsView`, `wordBandsView`, `hitAreasView`, `ayahMarksView`, `highlightBoxesView`,
+`maskBoxesView`, `hitTestView`, `hitTestExactView`, and `L.slots`. A host drawing its own
+overlay uses these and never places ink itself.
+
+The calls without `View` answer in page units, as the print has them: `wordBands`, `hitAreas`,
+`lineBands`, `ayahMarks`, `hitTest`, `hitTestExact`, `cropBounds` and `cropSvg`. They describe
+the printed page, which is what a crop exports and what a reflowed page no longer looks like.
+`hitAreasView` is not `hitAreas` transformed: a row's words have other neighbours than a
+printed line's, so the partition is computed again.
 
 ## Styles
 
@@ -125,7 +513,7 @@ const h = page.style(Sel.wordMark(w, 1), '#1a73e8', {ms: 200});     // the 2nd d
 page.styleTarget('2:255', '#0a7d32', {layer: LAYER.HIGHLIGHT});
 page.hide(Sel.kind('mark'));                                          // reading view without tashkil
 page.theme({ink: '#e8e4dc', diacritics: '#7fb0e8', dots: '#ff8a80', ayahMark: '#b8860b', ms: 300});
-page.restyle(h, '#ff0000', 100); page.unstyle(h); page.setDefaultInk('#231f20');
+page.recolorStyle(h, '#ff0000', 100); page.removeStyle(h); page.setDefaultColor('#231f20');
 ```
 
 Rules live in **layers** (`LAYER.BASE 0`, `THEME 10`, `HIGHLIGHT 50`, `SELECTION 60`,
@@ -146,7 +534,7 @@ function frame(now) {
 
 `Renderer.draw()` calls `page.buildPaths()` for you, and `buildPaths()` memoises, so a
 consumer using the supplied renderer never calls it directly. Call it yourself only when
-you write your own renderer on top of `paint()`/`styled()`: it turns the page's op/point
+you write your own renderer on top of `colors()`/`styledPaths()`: it turns the page's op/point
 arrays into the path objects those lists index, and drawing without it has nothing to
 fill.
 
@@ -160,65 +548,206 @@ ReferenceError: Path2D is not defined
 ```
 
 Everything above drawing is pure wasm and runs anywhere: loading, `words`/`ayahs`/`lines`,
-hit-testing, `layout()`, styles, `paint()` and `styled()` themselves. So a server-side or
+hit-testing, `layout()`, styles, `colors()` and `styledPaths()` themselves. So a server-side or
 worker consumer can use the engine for everything except the final fill, and should stop
 at the display list. The native bindings build paths against their own platform types
 (`CGPath`, `android.graphics.Path`, `ui.Path`) and have no such restriction.
 
-`paint()` is the full display list (a colour per path); `styled()` lists only the
+`colors()` is the full display list (a colour per path); `styledPaths()` lists only the
 paths that differ from the default ink, which is what the cached-base-layer renderer
-repaints. `highlightBoxes()` and `maskBoxes()` are viewport-px rectangles.
+repaints. `highlightBoxesView()` and `maskBoxesView()` are viewport-px rectangles.
 
 ## Highlights
 
 ```js
 const h = page.highlight('2:255', {mode: 'both', ink: '#0a7d32', band: '#0a7d3224',
-                                   height: 'pitch', padX: 1.2, radius: 1.5, seam: 0.25, ms: 250});
-page.rehighlight(h, '2:256');      // the band slides to the new words, ink cross-fades
+                                   height: 'lineSpacing', padX: 1.2, radius: 1.5, seam: 0.25, ms: 250});
+page.moveHighlight(h, '2:256');      // the band slides to the new words, ink cross-fades
 page.restyleHighlight(h, {...});   // recolour in place
-page.unhighlight(h);               // fades out, then disappears
+page.removeHighlight(h);               // fades out, then disappears
 ```
 
 `mode` is `ink`, `band` or `both`. A band is **one path per highlight** covering every
 printed line the words occupy, with a `seam` overlap so a six-line ayah reads as one
-shape and not six stripes; height is the line pitch or the words' ink. Use one handle
-and `rehighlight` for word-by-word following.
+shape and not six stripes; height is the line line spacing or the words' ink. Use one handle
+and `moveHighlight` for word-by-word following.
 
 ## Selection
 
 `select(anchor, focus)` snaps to whole words; `selection()`, `selectionText(form, withCitation)`.
-Draw the band with a highlight in `LAYER.SELECTION`; see `web/app.js` for drag-to-select.
+Draw the band with a highlight in `LAYER.SELECTION`; see `web/example/app.js` for drag-to-select.
 
 ## Memorisation
 
 ```js
-page.mask('2:255', 'hide' | 'block' | 'blur'); page.revealNext(1); page.hideBack(1);
-page.revealWord(i); page.revealAll(); page.hideAll(); page.unmask(); page.maskHidden()
+page.mask('2:255', 'hide' | 'block' | 'blur'); page.unmaskNext(1); page.maskBack(1);
+page.unmaskWord(i); page.unmaskAll(); page.maskAll(); page.unmask(); page.maskHidden()
 const steps = page.revealStart({lit: 2, byAyah: false, grey: '#c9c4b8', ink: '#231f20', ayahMarks: true, ms: 150});
 page.revealGoto(at); page.revealStop();
 ```
 
 `hide` keeps the page's shape (ink alpha 0). `block`/`blur` keep the ink and hand the
-host `maskBoxes()` to draw over. The greyed-page reveal lights a window of `lit` steps
+host `maskBoxesView()` to draw over. `qvp_mask_transition(ms)` (iOS `maskTransition`) fades
+`hide` words in and out on the engine clock instead of switching at once — the ink keeps
+its colour and only its alpha moves; `unmask()` resets it like the other mask options.
+The greyed-page reveal lights a window of `lit` steps
 ending at `at`; a medallion lights with the ayah it closes.
 
 ## Recitation
 
 `reciteMap(s, a, nSegments)` returns the words to pair with `nSegments` timings, or
 `null` when the counts disagree — then follow the ayah whole rather than drift.
-Drive the highlight with `rehighlight(h, T.word(i))`.
+Drive the highlight with `moveHighlight(h, T.word(i))`.
 
 ## Crop and export
 
-`cropBox(target, {pad, keepAyahMarks})`; `cropSvg(target, {pad, keepAyahMarks, background})`
+`cropBounds(target, {pad, keepAyahMarks})`; `cropSvg(target, {pad, keepAyahMarks, background})`
 returns a standalone SVG string with the current colours (masks, themes and highlights'
 ink applied). The medallion is kept only when the whole ayah is inside the crop.
 
 ## Atlas (cross-page)
 
 `atlas.pageOf(s,a)`, `pageRange(page)`, `surah(n)`, `surahs()`, `pageOfSurah(n)`,
-`juz(n)/hizb(n)/rubuAlHizb(n)` → `{surah, ayah, page}`, `juzAt(s,a)`, `divisionAt(kind, s, a)`,
-`pagesOfJuz(n)`, `findSurah('cow' | 'البقرة' | '2')`.
+`juz(n)/hizb(n)/rubuAlHizb(n)` → `{surah, ayah, page}`, `juzOf(s,a)`, `divisionOf(division, s, a)`,
+`pagesOfJuz(n)`, `searchSurahs('cow' | 'البقرة' | '2')`.
+
+## Names
+
+```js
+engine.names('mark')            // every name of a table, index = id: 'mark' | 'kind' | 'family' |
+                                //   'category' | 'decoration' | 'division' | 'place'
+engine.name('decoration', 0)    // 'ayah-mark'
+engine.nameId('mark', 'shaddah')  // 7; 255 when the table has no such name
+engine.nameCount('mark')        // 36
+```
+
+The engine holds every name table. A wrapper reads them from the engine when it starts
+(`Sel.mark('shaddah')`, `Sel.decoration('ayah-mark')` and the rest resolve through them) and
+carries no table of its own; a name the engine does not have resolves to 255, never to 0.
+
+## Every symbol
+
+One row per C function, with its spelling in the reference wrapper (`web/qvp.js`; the other
+wrappers use the same names in their own casing) and what it does. `docs/API-PARITY.md`
+says which wrapper binds which.
+
+| section | C | reference wrapper | what it does |
+|---|---|---|---|
+| memory | `qvp_alloc` | engine internal | Allocate `len` bytes inside the engine's memory, for hosts without their own allocator (wasm). |
+| memory | `qvp_dealloc` | engine internal | Free bytes from `qvp_alloc`. |
+| page | `qvp_page_load` | `engine.loadPage(bytes)` | Decode a page file into a page handle; null on a malformed file; the bytes are copied. |
+| page | `qvp_page_free` | `page.free()` | Free the page handle. |
+| page | `qvp_page_info` | `page.width`, `.height`, `.page`, `.nLines`, `.nAyahs`, `.nWords`, `.nPaths`, `.nDecorations` | Return the page's dimensions and element counts. |
+| page | `qvp_geometry` | `page.paths`, `page.buildPaths()` | Return the outline streams and the per-path table a renderer draws from; they live as long as the page. Ink outside the page's box gets no outline, so a host draws the page and not what the artwork left beyond it. |
+| page | `qvp_word_info` | `page.words[i]` | Return one word: key, line, ayah fragment, bounds, text and its path range. |
+| page | `qvp_word_form` | `page.wordForm(i, form)` | Return one of a word's text forms; the derived forms need the words sidecar. |
+| page | `qvp_ayah_info` | `page.ayahs[i]` | Return one ayah fragment: key, fragment index and count, flags, word range, ayah-mark decoration, bounds. |
+| page | `qvp_line_info` | `page.lines[i]` | Return one printed line: number, header flag, word range, bounds, band and centre. |
+| page | `qvp_decoration_info` | `page.decorations[i]` | Return one decoration: its `QVP_DECORATION_*` value, key, line, bounds, text and its path range. |
+| page | `qvp_find_word` | `page.findWord(surah, ayah, word)` | Return the page index of a word by its key, or −1 when the word is not on this page. |
+| page | `qvp_target_words` | `page.targetWords(target)` | Expand a target (page, word, ayah, range, line, surah) into word indices in reading order. |
+| page | `qvp_page_line_spacing` | `page.lineSpacing` | Return the printed line spacing of this page, in page units. |
+| page | `qvp_page_grid` | `page.grid` | Return the grid the page is laid out inside: the mushaf's line count and the printed line spacing. |
+| metadata | `qvp_surah_count` | `page.surahs().length` | Return how many surahs have text on this page. |
+| metadata | `qvp_surah_at` | `page.surahs()[i]` | Return the i-th surah on the page: number, ayah count, banner and basmalah flags, place, names. |
+| metadata | `qvp_divisions` | `page.divisions()` | Return the juz, hizb, nisf and rubu_al_hizb divisions that start on this page. |
+| metadata | `qvp_ayah_marks` | `page.ayahMarks()` | Return the ayah-mark medallions on the page with their centres and radii. |
+| metadata | `qvp_rosettes` | `page.rosettes()` | Return the drawn hizb rosettes with the division numbers they mark. |
+| metadata | `qvp_sajdahs` | `page.sajdahs()` | Return the sajdah signs on the page. |
+| metadata | `qvp_ayah_keys` | `page.ayahKeys()` | Return the ayah keys on the page in reading order, packed as surah in the high 16 bits and ayah in the low 16. |
+| metadata | `qvp_ayah_word_count` | `page.ayahWordCount(surah, ayah)` | Return how many of an ayah's words are on this page and whether the ayah is complete here. |
+| metadata | `qvp_recite_map` | `page.reciteMap(surah, ayah, nSegments)` | Map an ayah's words onto `nSegments` recitation timings, or −1 when the counts disagree. |
+| metadata | `qvp_word_label` | `page.wordLabel(i)` | Return an accessibility label for a word. |
+| metadata | `qvp_ayah_label` | `page.ayahLabel(i)` | Return an accessibility label for an ayah fragment. |
+| text and search | `qvp_text` | `page.text(target, form, wordSep, lineSep)` | Return the text of a target (the page by default) in one form, with the given separators. |
+| text and search | `qvp_search` | `page.search(query, …)` | Search the page's words in one text form with Arabic normalisation; returns matches with their word index. |
+| text and search | `qvp_arabic` | `engine.strip()`, `.fold()`, `.normalize()`, `.looseKey()`, `.searchKey()` | Apply one of the Arabic text transforms of the search fold to a string. |
+| text and search | `qvp_citation` | `page.citation(words)` | Return a citation such as `2:255-257, 3:1` for a word list. |
+| text and search | `qvp_attach_words` | `page.attachWords(json)` | Attach the words sidecar's text forms; returns the number of words updated, −1 on bad JSON. |
+| text and search | `qvp_has_form` | `page.hasForm(form)` | Return whether a text form is available (the derived forms need the sidecar). |
+| hit testing | `qvp_hit_test_exact` | `page.hitTestExact(x, y)` | Return the word, path or decoration whose exact outline contains a point in page units. |
+| hit testing | `qvp_hit_test_exact_view` | `page.hitTestExactView(viewX, viewY)` | The same for a point in viewport pixels through the current layout. |
+| hit testing | `qvp_hit_test` | `page.hitTest(x, y, options)` | Gap-aware: resolve a point to the nearest word by line band and gap bias, with the distance and whether the hit was exact. |
+| hit testing | `qvp_hit_test_view` | `page.hitTestView(viewX, viewY, options)` | The same for viewport pixels. |
+| hit testing | `qvp_line_bands` | `page.lineBands()` | Return every line's vertical band in page units. |
+| hit testing | `qvp_hit_areas` | `page.hitAreas(gapBias)` | Return the gap-aware rectangle of every word, a partition of each line with no dead zone. |
+| layout | `qvp_layout` | `page.layout(spec)` | Lay the page out for a viewport: scale, per-line shifts, slots, content size and the fit transform. |
+| layout | `qvp_layout_line_spacing_to_fill` | `page.layoutLineSpacingToFill(spec, max)` | Return the `lineSpacing` multiplier that fills the padded viewport of a spec when fitted to width. |
+| layout | `qvp_layout_wasted_fraction` | `page.layoutWastedFraction(spec)` | Return the share of the padded viewport of a spec left empty when the page is fitted to width. |
+| layout | `qvp_layout_printed_height` | `page.layoutPrintedHeight(spec)` | Return the page's height laid out for a spec at the printed pitch, in viewport px: `contentH` before fill-height adds any leading. |
+| layout | `qvp_word_bounds_view` | `page.wordBoundsView(i)` | Return a word's bounds in viewport pixels through the current layout. |
+| styles | `qvp_style_add` | `page.style(selector, colour, ms, layer)` | Add a colour rule for a selector on a layer; returns a handle, 0 for a bad selector. |
+| styles | `qvp_style_add_target` | `page.styleTarget(target, colour, ms, layer)` | Add a colour rule for a target's words. |
+| styles | `qvp_style_remove` | `page.removeStyle(handle)` | Remove a rule by handle; returns how many rules were removed. |
+| styles | `qvp_style_recolor` | `page.recolorStyle(handle, colour, ms)` | Change a rule's colour in place, with a transition. |
+| styles | `qvp_style_clear` | `page.clearStyles()` | Remove every rule. |
+| styles | `qvp_style_clear_layer` | `page.clearLayer(layer)` | Remove every rule on one layer. |
+| styles | `qvp_style_default_color` | `page.setDefaultColor(colour)` | Set the ink colour a path has when no rule applies. |
+| styles | `qvp_style_hide` | `page.hide(selector)` | Add an alpha-0 rule on the top layer; returns its handle. |
+| styles | `qvp_theme` | `page.theme(theme)` | Apply a theme (ink, mark families, headers) as one rule set with one handle. |
+| styles | `qvp_style_handles` | `page.styleHandles()` | Return the handles of every live rule. |
+| clock and colours | `qvp_tick` | `page.tick(nowMs)` | Advance transitions to a time; returns 1 while anything is still animating. |
+| clock and colours | `qvp_colors` | `page.colors()` | Return the current colour of every path, mid-transition included. |
+| clock and colours | `qvp_styled_paths` | `page.styledPaths()` | Return the (path, colour) pairs whose colour differs from the default ink. |
+| clock and colours | `qvp_color_of` | `page.colorOf(path)` | Return one path's current colour. |
+| highlights | `qvp_highlight_add` | `page.highlight(target, style)` | Add a highlight (ink, band or both) for a target; returns a handle. |
+| highlights | `qvp_highlight_move` | `page.moveHighlight(handle, target)` | Move a highlight to another target: the band slides, the ink cross-fades. |
+| highlights | `qvp_highlight_restyle` | `page.restyleHighlight(handle, style)` | Change a highlight's style in place. |
+| highlights | `qvp_highlight_remove` | `page.removeHighlight(handle)` | Fade a highlight out and remove it. |
+| highlights | `qvp_highlight_clear` | `page.clearHighlights()` | Remove every highlight. |
+| highlights | `qvp_highlight_handles` | `page.highlightHandles()` | Return the handles of every live highlight. |
+| highlights | `qvp_highlight_words` | `page.highlightWords(handle)` | Return the words a highlight covers. |
+| highlights | `qvp_highlight_boxes_view` | `page.highlightBoxesView()` | Return every highlight's band rectangles in viewport pixels; draw each id as one nonzero path behind the ink. |
+| highlights | `qvp_word_bands` | `page.wordBands(words, options)` | Return band rectangles for an arbitrary word list, in page units. |
+| selection | `qvp_select` | `page.select(anchor, focus)` | Select the whole words between two word indices; `QVP_NONE` clears. |
+| selection | `qvp_selection` | `page.selection()` | Return the selected word indices. |
+| selection | `qvp_selection_text` | `page.selectionText(form, citation)` | Return the selected text, with its citation when asked. |
+| memorisation | `qvp_mask` | `page.mask(target, mode)` | Mask a target's words: hide, block or blur. |
+| memorisation | `qvp_mask_from` | `page.maskFrom(word, mode)` | Mask every word from a word index to the end of the page. |
+| memorisation | `qvp_mask_options` | `page.maskOptions(options)` | Set the block colour, padding, radius and direction of the mask. |
+| memorisation | `qvp_unmask_next` | `page.unmaskNext(n)` | Unhide the next `n` masked words; returns how many are still hidden. |
+| memorisation | `qvp_mask_back` | `page.maskBack(n)` | Re-hide the last `n` revealed words. |
+| memorisation | `qvp_unmask_word` | `page.unmaskWord(i)` | Unhide one word. |
+| memorisation | `qvp_mask_word` | `page.maskWord(i)` | Hide one word again. |
+| memorisation | `qvp_unmask_all` | `page.unmaskAll()` | Unhide every masked word. |
+| memorisation | `qvp_mask_all` | `page.maskAll()` | Hide every word in the mask again. |
+| memorisation | `qvp_unmask` | `page.unmask()` | Remove the mask. |
+| memorisation | `qvp_mask_hidden` | `page.maskHidden()` | Return the words currently hidden. |
+| memorisation | `qvp_mask_words` | `page.maskWords()` | Return the words in the mask's scope. |
+| memorisation | `qvp_mask_boxes_view` | `page.maskBoxesView()` | Return the block or blur rectangles in viewport pixels for the host to draw. |
+| memorisation | `qvp_reveal_start` | `page.revealStart(options)` | Grey the page and light a moving window of steps; returns the step count. |
+| memorisation | `qvp_reveal_goto` | `page.revealGoto(at)` | Light the window ending at a step; −1 when nothing is lit yet. |
+| memorisation | `qvp_reveal_position` | `page.revealPosition()` | Return the current step, −2 when no reveal is running. |
+| memorisation | `qvp_reveal_step_count` | `page.revealStepCount()` | Return the number of steps in the running reveal. |
+| memorisation | `qvp_reveal_step_of` | `page.revealStepOf(i)` | Return the step that lights a word. |
+| memorisation | `qvp_reveal_stop` | `page.revealStop()` | End the reveal and restore the page. |
+| crop | `qvp_crop_bounds` | `page.cropBounds(target, options)` | Return the crop rectangle of a target with padding, and whether the ayah mark is inside it. |
+| crop | `qvp_crop_svg` | `page.cropSvg(target, options)` | Return a standalone SVG of a target with the current colours applied. |
+| atlas | `qvp_atlas_load` | `engine.loadAtlas(bytes)` | Decode the atlas file; null on a malformed file. |
+| atlas | `qvp_atlas_free` | `atlas.free()` | Free the atlas. |
+| atlas | `qvp_atlas_page_of` | `atlas.pageOf(surah, ayah)` | Return the page an ayah is on. |
+| atlas | `qvp_atlas_page_range` | `atlas.pageRange(page)` | Return the first and last ayah keys of a page. |
+| atlas | `qvp_atlas_page_count` | `atlas.pageCount()` | Return how many pages the atlas covers. |
+| atlas | `qvp_atlas_surah_count` | `atlas.surahs()` | Return how many surahs the atlas covers. |
+| atlas | `qvp_atlas_surah` | `atlas.surah(n)` | Return a surah by number: first page, ayah count, place, names. |
+| atlas | `qvp_atlas_surah_at` | `atlas.surahs()[i]` | Return the i-th surah record. |
+| atlas | `qvp_atlas_division` | `atlas.juz(n)`, `.hizb(n)`, `.nisf(n)`, `.rubuAlHizb(n)` | Return where a division starts: surah, ayah, page. |
+| atlas | `qvp_atlas_division_of` | `atlas.juzOf(surah, ayah)`, `.divisionOf(division, surah, ayah)` | Return the number of the division that contains an ayah. |
+| atlas | `qvp_atlas_pages_of_juz` | `atlas.pagesOfJuz(n)` | Return the first and last page of a juz. |
+| atlas | `qvp_atlas_search_surahs` | `atlas.searchSurahs(text)` | Search the surah names in Arabic, Latin or English, or by number. |
+| atlas | `qvp_atlas_json` | `atlas.json()` | Return the atlas as JSON. |
+| names | `qvp_name_count` | `engine.nameCount(table)` | Return how many ids a name table has. |
+| names | `qvp_name` | `engine.name(table, id)` | Return the name of an id in a table; empty outside the table. |
+| names | `qvp_name_id` | `engine.nameId(table, name)` | Return the id of a name in a table; 255 when the table has no such name. |
+| names | `qvp_mark_name` | `engine.markName(id)` | Return a mark's name. |
+| names | `qvp_family_name` | `engine.familyName(id)` | Return a mark family's name. |
+| names | `qvp_kind_name` | `engine.kindName(id)` | Return a path kind's name. |
+| names | `qvp_category_name` | `engine.categoryName(id)` | Return a mark category's name. |
+| names | `qvp_mark_from_name` | `engine.markFromName(name)` | Return a mark's id by name; 255 when unknown. |
+| names | `qvp_mark_category` | `engine.markCategory(id)` | Return the category a mark belongs to. |
+| names | `qvp_version` | `engine.version()` | Return the engine version as a string, `0.2.0`. |
+| names | `qvp_format_version` | `engine.formatVersion()` | Return the page format version the engine reads. |
+| names | `qvp_engine_name` | `engine.engineName()` | Return the engine's name, `qvp`. |
 
 ## C ABI notes