@quran.ws/engine 0.1.0

package/LICENSE

@@ -0,0 +1,172 @@
+Copyright 2026 Quran.ws
+
+This work is dedicated as a waqf for the sake of Allah, seeking His pleasure
+through the benefit it brings to people. We publish it to enable the widest
+possible beneficial use, with as few restrictions as possible.
+
+Quran.ws publishes code under the MIT License, and data and content under the
+Creative Commons Attribution 4.0 International License,
+with a standing waiver of attribution for use inside a product.
+
+We license only what we have the right to license; third-party material keeps
+the licence and terms of its own rights holders.
+
+Full policy: https://github.com/quran-ws/guidelines
+
+
+═══════════════════════════════════════════════════════════════════════════════
+WHAT IS COVERED BY WHAT
+═══════════════════════════════════════════════════════════════════════════════
+
+  crates/   MIT
+  docs/     CC BY 4.0
+  packages/ MIT
+  scripts/  MIT
+  web/      MIT
+
+Where a directory or file carries its own LICENSE or NOTICE, that notice
+governs for that material. Names, logos and trademarks are not licensed.
+
+
+═══════════════════════════════════════════════════════════════════════════════
+ATTRIBUTION WAIVED FOR USE IN PRODUCTS
+═══════════════════════════════════════════════════════════════════════════════
+
+As rights holders of our original data and content, we grant a permanent,
+worldwide, royalty-free, irrevocable waiver of the attribution requirement of
+CC BY 4.0 (Section 3(a)) when the material is used within an application,
+website, service, API, bot, tool, research work, or product, whether free or
+commercial. This permission expands what you may do and adds no restriction to
+CC BY 4.0.
+
+Attribution is still required on republication — when the data or content
+itself is made available to others as a resource in its own right. The test:
+if a third party can obtain the data AS DATA from what you distribute, that is
+republication, and CC BY 4.0 attribution applies.
+
+Suggested attribution:
+
+  Data from [resource] by Quran.ws, licensed under CC BY 4.0.
+  Source: [canonical URL]. Version: [version]. Modified: [yes/no].
+
+Use for training, fine-tuning, evaluating, indexing or retrieval by machine
+learning systems is permitted and treated as use, not republication.
+
+
+═══════════════════════════════════════════════════════════════════════════════
+THIRD-PARTY MATERIAL — KING FAHD GLORIOUS QUR'AN PRINTING COMPLEX
+═══════════════════════════════════════════════════════════════════════════════
+
+The Qur'anic text editions, mushaf typesettings and fonts in this repository
+derive from material published by the King Fahd Glorious Qur'an Printing
+Complex. That material is not ours to license. It is used under the Complex's
+own published usage rights, reproduced in full below in Arabic and English.
+
+Our processing, correction, organisation or transformation of that material
+creates no ownership in it and does not override these terms.
+
+
+───────────────────────────────────────────────────────────── حقوق الاستخدام ───
+
+بناء على موافقة معالي وزير الشؤون الإسلامية والدعوة والإرشاد، المشرف العام على
+مجمع الملك فهد لطباعة المصحف الشريف، يتشـرَّف المجمع بإتاحة نسخة رقمية كاملة من
+مصحف المدينة النبوية المطبوع في المجمع، وذلك بالصيغ التالية:
+
+رسم المتجهات Illustrator
+وثيقة بي دي إف PDF
+صور ذات جودة عالية Images
+خط حاسوبي True Type Font
+
+ويمكن استخدام النسخة المذكورة مجاناً في المجالات الشخصية والأعمال الفردية كافة،
+وأعمال الجهات الحكومية والجهات والمؤسسات الخاصة والأهلية، وأعمال الطباعة
+الورقية*، والنشـر المكتبي والإعلامي، ومواقع الإنترنت والبرامج الحاسوبية وغيرها،
+وذلك داخل المملكة العربية السعودية وخارجها.
+
+نسأل الله أن ينفع المسلمين بهذا العمل المبارك.
+
+والحمد لله رب العالمين
+
+* أعمال طباعة المصاحف داخل المملكة واستيرادها من الخارج لغرض البيع التجاري
+تخضع للأمر السامي الكريم ذي الرقم 136/8 المؤرخ في 1/2/1406هـ وأكّد على ذلك
+الأمر السامي الكريم رقم 9/ب/46356 بتاريخ 28/9/1424هـ. والذي وجه بمنع طباعة
+المصاحف في الداخل في غير المجمع، وكذلك منع استيرادها من الخارج لغرض البيع
+التجاري.
+
+
+──────────────────────────────────────────────────────────────── Copyright ────
+
+Based on the approval of His Excellency the Minister of Islamic Affairs,
+Endowments, Da'wah and Guidance, General Supervisor of the King Fahd Qur'an
+Printing Complex.
+
+The Qur'an Printing Complex is honored to present to the Muslim public a
+complete free digital copy of Mus'haf al-Madinah published by the Complex, in
+the following formats:
+
+  • Adobe Illustrator files
+  • PDF files
+  • High quality images
+  • True Type Font
+
+Mus'haf al-Madinah in these previous formats can be used for free in all
+personal, individual businesses, in works of governmental departments &
+agencies, in the publications of both private and national institutions, also
+suitable for Qur'an printing,* digital publishing, & for media use, can be used
+also in websites, software, and other similar intermediates.
+
+We ask Allah that He renders this blessed project beneficial to all Muslims.
+
+* Printing of Qur'anic copies in the Kingdom, and their import from outside for
+sale are subject to the Royal Decree No 136/8 dated 1/2/1406 AH which has been
+reiterated by the Royal Decree No 9/B/46356 dated 28/9/1424 AH which prohibit
+printing of Qur'anic copies in the Kingdom except in the Complex, likewise
+their import from outside for sale.
+
+
+═══════════════════════════════════════════════════════════════════════════════
+ACCURACY AND NO WARRANTY
+═══════════════════════════════════════════════════════════════════════════════
+
+This material is provided AS IS, without warranty of any kind, as stated in
+the MIT License and in CC BY 4.0 (Sections 5 and 6).
+
+Qur'anic text, transliteration, translation, recitation and mushaf rendering
+may contain errors, and releases are corrected over time. Anyone publishing
+Qur'anic text to end users is responsible for verifying it against an
+authorised printed mushaf and for tracking our corrections.
+
+Corrections:          corrections@quran.ws — treated as a priority.
+Licensing questions:  legal@quran.ws
+
+
+═══════════════════════════════════════════════════════════════════════════════
+FULL LICENCE TEXTS
+═══════════════════════════════════════════════════════════════════════════════
+
+The full CC BY 4.0 legal text is in LICENSES/CC-BY-4.0.txt and at
+https://creativecommons.org/licenses/by/4.0/legalcode
+
+MIT License
+
+Copyright (c) 2026 Quran.ws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+This notice is published in Arabic and English. Where the two differ, the
+Arabic version governs.

package/LICENSES/CC-BY-4.0.txt

@@ -0,0 +1,156 @@
+Creative Commons Attribution 4.0 International
+
+ Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+Considerations for licensors: Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. More considerations for licensors.
+
+Considerations for the public: By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. More considerations for the public.
+
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+Section 1 – Definitions.
+
+     a.	Adapted Material means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+     b.	Adapter's License means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+     c.	Copyright and Similar Rights means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+     d.	Effective Technological Measures means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+     e.	Exceptions and Limitations means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+     f.	Licensed Material means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+     g.	Licensed Rights means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+     h.	Licensor means the individual(s) or entity(ies) granting rights under this Public License.
+
+     i.	Share means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+     j.	Sui Generis Database Rights means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+     k.	You means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+Section 2 – Scope.
+
+     a.	License grant.
+
+          1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+               A. reproduce and Share the Licensed Material, in whole or in part; and
+
+               B. produce, reproduce, and Share Adapted Material.
+
+          2. Exceptions and Limitations. For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+          3. Term. The term of this Public License is specified in Section 6(a).
+
+          4. Media and formats; technical modifications allowed. The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+          5. Downstream recipients.
+
+               A. Offer from the Licensor – Licensed Material. Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+               B. No downstream restrictions. You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+          6.  No endorsement. Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+b. Other rights.
+
+          1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+          2. Patent and trademark rights are not licensed under this Public License.
+
+          3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+     a.	Attribution.
+
+          1. If You Share the Licensed Material (including in modified form), You must:
+
+               A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+                    i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+                    ii. a copyright notice;
+
+                    iii. a notice that refers to this Public License;
+
+                    iv.	a notice that refers to the disclaimer of warranties;
+
+                    v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+               B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+               C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+          2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+          3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+          4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
+
+Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+     a.	for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+     b.	if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
+
+     c.	You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+     a.	Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.
+
+     b.	To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.
+
+     c.	The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+Section 6 – Term and Termination.
+
+     a.	This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+     b.	Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+          1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+          2. upon express reinstatement by the Licensor.
+
+     c.	For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+     d.	For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+     e.	Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+Section 7 – Other Terms and Conditions.
+
+     a.	The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+     b.	Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+Section 8 – Interpretation.
+
+     a.	For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+     b.	To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+     c.	No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+     d.	Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at creativecommons.org/policies, Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+
+Creative Commons may be contacted at creativecommons.org.

package/README.md

@@ -0,0 +1,53 @@
+<div align="center">
+
+<img src=".github/banner.svg" alt="Quran Engine — Rendering, Beta" width="820">
+
+**A rendering engine for interactive Mushaf pages that uses each platform's native graphics APIs.**
+
+<a href="https://quran.ws/blocks/quran-engine"><img alt="See it work" src="https://img.shields.io/badge/See_it_work-15705D?style=for-the-badge&labelColor=102F29"></a>
+<a href="https://quran.ws/docs/reference/quran-engine"><img alt="Documentation" src="https://img.shields.io/badge/Documentation-102F29?style=for-the-badge&labelColor=102F29"></a>
+
+</div>
+
+Use it when building Quran applications for mobile or desktop and you need fast, lightweight page rendering with interactive access to page elements.
+
+> محرّك لعرض صفحات المصحف التفاعلية بكفاءة باستخدام الرسم الأصلي لكل منصة.
+>
+> استخدمه عند بناء تطبيقات القرآن على الجوال أو سطح المكتب عندما تحتاج عرضًا سريعًا وخفيفًا لصفحات المصحف مع إمكانية التفاعل مع عناصرها.
+
+| | |
+|---|---|
+| **Package** | `@quran.ws/engine` · `0.1.0` |
+| **Whole mushaf** | 38.9 MB brotli |
+| **Wasm engine** | 311 KB |
+| **Licence** | MIT (the code) · source bundle terms (the data) |
+
+```sh
+# not published — build the wasm, or take it from the release
+```
+
+## Where the documentation is
+
+Everything about using it lives on the site. This repository is the source.
+
+| | |
+|---|---|
+| **Overview and demo** | [quran.ws/blocks/quran-engine](https://quran.ws/blocks/quran-engine) |
+| **Reference** | [quran.ws/docs/reference/quran-engine](https://quran.ws/docs/reference/quran-engine) |
+| **Make words clickable** | [quran.ws/docs/build/clickable-words](https://quran.ws/docs/build/clickable-words) |
+| **Render on iOS, Android, Flutter and React Native** | [quran.ws/docs/build/platforms](https://quran.ws/docs/build/platforms) |
+| **Work offline** | [quran.ws/docs/build/offline](https://quran.ws/docs/build/offline) |
+| **Licensing in full** | [quran.ws/docs/reference/licensing](https://quran.ws/docs/reference/licensing) |
+
+## What is in here
+
+| | |
+|---|---|
+| `crates/` | the Rust core: `qvp-format`, `qvp-core`, `qvp-convert`, `qvp-ffi` |
+| `packages/` | the thin platform wrappers — iOS, Android, Flutter, React Native |
+| `web/` | the reference web harness the browser demo runs on |
+| `conformance/` | the gates that must stay green |
+| `scripts/` | build and packaging |
+| `docs/` | the API, the format, and the measured numbers |
+
+Issues and pull requests are welcome here. Everything that is not about *changing* this repository is on the site.

package/docs/API.md

@@ -0,0 +1,228 @@
+# QVP engine API
+
+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.
+
+**Conventions**
+
+- **Colours** are `0xRRGGBBAA`. Alpha 0 means *hidden* in a style and *leave alone* in a theme.
+  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*.
+- **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),
+  `'2:255-257'`, `'line:7'`, `'surah:2'`, a word index, an array of word indices, or a
+  `T.*` constructor.
+- **Selectors** say what a style rule applies to, from a whole page down to *the second
+  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.
+
+## Loading
+
+```js
+const engine = await QvpEngine.init(wasmBytes);           // native: QvpEngine(library path)
+const page   = engine.loadPage(await fetchBytes('pages/042.qvp'));
+const atlas  = engine.loadAtlas(await fetchBytes('pages/atlas.qva'));   // optional
+page.attachWords(await fetchJson('pages/042.words.json'));               // optional forms
+page.free(); atlas.free();
+```
+
+`page.width/height/page/nLines/nAyahs/nWords/nPaths/nDecos`, `page.naturalPitch`.
+
+## 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.findWord(s,a,w)` | index or −1 |
+| `page.resolve(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
+continues on another page.
+
+## 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)`,
+`ayahLabel(i)` for screen readers.
+
+## Text and search
+
+```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.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)
+```
+
+Search normalises both sides (strip marks + fold) and, when the strict pass finds
+nothing, retries with the loose key so a typed `الرحمان` finds the printed `الرحمن`.
+Modes: `includes`, `exact`, `prefix`. Without a sidecar it searches the stripped `rasm_uthmani`.
+
+## Hit testing
+
+```js
+page.hitTestViewEx(vx, vy, {maxDistance: 6, gapBias: 0.6})
+// → {word, path, deco, line, distance, exact, 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
+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.
+
+## 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[]}
+```
+
+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
+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.
+
+## Styles
+
+```js
+const h = page.style(Sel.wordMark(w, 1), '#1a73e8', {ms: 200});     // the 2nd diacritic only
+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');
+```
+
+Rules live in **layers** (`LAYER.BASE 0`, `THEME 10`, `HIGHLIGHT 50`, `SELECTION 60`,
+`TOP 100`, or any integer). Resolution per path: highest layer wins, then the most
+specific selector, then the newest rule. Every rule carries a `ms` transition; colours
+fade on the engine clock. Precedence around rules: masked words are hidden above
+everything; the greyed-page reveal sits below rules and above the default ink.
+
+## Clock and display list
+
+```js
+function frame(now) {
+  const moving = page.tick(now);          // advance fades and band slides
+  renderer.draw(page, view, dpr);         // bands → base ink → styled ink → mask boxes
+  if (moving) requestAnimationFrame(frame);
+}
+```
+
+`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
+arrays into the path objects those lists index, and drawing without it has nothing to
+fill.
+
+`buildPaths()` constructs `Path2D`, and so does `drawBoxes()` — `Path2D` is a DOM
+interface, so **everything from `buildPaths()` down is browser-only**. In Node or in a
+worker without a DOM the call fails at its first path:
+
+```console
+$ node -e 'new Path2D()'
+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
+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
+paths that differ from the default ink, which is what the cached-base-layer renderer
+repaints. `highlightBoxes()` and `maskBoxes()` 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
+page.restyleHighlight(h, {...});   // recolour in place
+page.unhighlight(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.
+
+## 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.
+
+## 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()
+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
+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))`.
+
+## Crop and export
+
+`cropBox(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')`.
+
+## C ABI notes
+
+Struct layouts, enums and every function signature are in `qvp.h`. Arrays are
+returned through `(out, cap)` and the call returns the total count; strings through
+`QvpStr {ptr, len}` valid until the next string-returning call on the same thread.
+`qvp_alloc/qvp_dealloc` exist for hosts without `malloc` (wasm).

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quran.ws/engine",
+  "version": "0.1.0",
+  "description": "Rendering engine for interactive muṣḥaf pages: layout, hit-testing, styling and search over the QVP page format, as wasm with a Canvas2D wrapper.",
+  "license": "MIT",
+  "homepage": "https://quran.ws/blocks/quran-engine",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quran-ws/quran-engine.git"
+  },
+  "bugs": {
+    "url": "https://github.com/quran-ws/quran-engine/issues"
+  },
+  "keywords": [
+    "quran",
+    "mushaf",
+    "arabic",
+    "wasm",
+    "canvas",
+    "rendering",
+    "qvp"
+  ],
+  "type": "module",
+  "sideEffects": [
+    "./web/qvp.js",
+    "./web/index.mjs",
+    "./web/index.cjs"
+  ],
+  "exports": {
+    ".": {
+      "import": "./web/index.mjs",
+      "require": "./web/index.cjs"
+    },
+    "./qvp.js": "./web/qvp.js",
+    "./qvp_ffi.wasm": "./web/qvp_ffi.wasm",
+    "./package.json": "./package.json"
+  },
+  "main": "./web/index.cjs",
+  "module": "./web/index.mjs",
+  "files": [
+    "web/index.mjs",
+    "web/index.cjs",
+    "web/qvp.js",
+    "web/qvp_ffi.wasm",
+    "docs/API.md",
+    "README.md",
+    "LICENSE",
+    "LICENSES/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build:wasm": "cargo build -p qvp-ffi --release --target wasm32-unknown-unknown && cp target/wasm32-unknown-unknown/release/qvp_ffi.wasm web/qvp_ffi.wasm",
+    "prepack": "npm run build:wasm",
+    "test": "node web/smoke.mjs"
+  }
+}

package/web/index.cjs

@@ -0,0 +1,10 @@
+// CommonJS entry for @quran.ws/engine. See index.mjs for why this shim exists.
+require('./qvp.js');
+
+const QVP = globalThis.QVP;
+if (!QVP) throw new Error('@quran.ws/engine: qvp.js did not define globalThis.QVP');
+
+/** Absolute path of the bundled `qvp_ffi.wasm`, for fs/fetch. */
+QVP.wasmPath = require('node:path').join(__dirname, 'qvp_ffi.wasm');
+
+module.exports = QVP;

package/web/index.mjs

@@ -0,0 +1,21 @@
+// ESM entry for @quran.ws/engine.
+//
+// qvp.js is the reference wrapper and is written as an IIFE that assigns a
+// single global, so that a plain <script> tag works with no build step. That
+// shape cannot be imported, so this file loads it for its side effect and
+// re-exports what it defined. The wrapper itself is unchanged.
+import './qvp.js';
+
+const QVP = globalThis.QVP;
+if (!QVP) throw new Error('@quran.ws/engine: qvp.js did not define globalThis.QVP');
+
+export const {
+  QvpEngine, QvpPage, QvpAtlas, CanvasRenderer,
+  Sel, T, KIND, FAMILY, CATEGORY, DECO, FORM, LAYER, MARK, MARKS, NONE,
+  css, rgba, parseTarget,
+} = QVP;
+
+/** Absolute URL of the bundled `qvp_ffi.wasm`, for fetch/instantiate. */
+export const wasmUrl = new URL('./qvp_ffi.wasm', import.meta.url);
+
+export default QVP;

package/web/qvp.js

@@ -0,0 +1,492 @@
+// QVP web wrapper — the reference thin wrapper over the C ABI (qvp_ffi.wasm).
+// Host renderer: Canvas2D. Everything that decides (hit-testing, layout, styles,
+// highlights, masks, search, text) lives in the engine; this file only marshals
+// and draws. API shape is mirrored by the Kotlin, Dart and React Native wrappers.
+(function (global) {
+  'use strict';
+
+  const NONE = 0xffffffff;
+  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 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));
+
+  // colours: numbers are 0xRRGGBBAA; strings '#rgb', '#rrggbb', '#rrggbbaa'
+  function rgba(c, alpha) {
+    if (typeof c === 'number') return c >>> 0;
+    if (typeof c !== 'string') return 0;
+    let h = c.trim().replace('#', '');
+    if (h.length === 3 || h.length === 4) h = [...h].map(x => x + x).join('');
+    if (h.length === 6) h += alpha !== undefined ? Math.round(alpha * 255).toString(16).padStart(2, '0') : 'ff';
+    return parseInt(h, 16) >>> 0;
+  }
+  const css = c => `rgba(${(c >>> 24) & 255},${(c >>> 16) & 255},${(c >>> 8) & 255},${(c & 255) / 255})`;
+
+  // 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 }),
+  };
+  const markId = m => (typeof m === 'string' ? (MARK[m] ?? 255) : 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 }),
+  };
+
+  class QvpEngine {
+    static async init(wasmBytes) {
+      const { instance } = await WebAssembly.instantiate(wasmBytes, {});
+      return new QvpEngine(instance);
+    }
+    constructor(instance) {
+      this.ex = instance.exports;
+      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.td = new TextDecoder();
+      this.te = new TextEncoder();
+    }
+    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)); }
+    /** 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'; }
+    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)); }
+    /** 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); }
+    loadPage(bytes) {
+      const p = this.ex.qvp_alloc(bytes.length);
+      new Uint8Array(this.mem.buffer, p, bytes.length).set(bytes);
+      const h = this.ex.qvp_page_load(p, bytes.length);
+      this.ex.qvp_dealloc(p, bytes.length);
+      if (!h) throw new Error('qvp_page_load failed');
+      return new QvpPage(this, h);
+    }
+    loadAtlas(bytes) {
+      const p = this.ex.qvp_alloc(bytes.length);
+      new Uint8Array(this.mem.buffer, p, bytes.length).set(bytes);
+      const h = this.ex.qvp_atlas_load(p, bytes.length);
+      this.ex.qvp_dealloc(p, bytes.length);
+      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);
+    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);
+    return at;
+  }
+  function parseTarget(s) {
+    if (s === 'page') return T.page();
+    let m;
+    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+)$/.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);
+    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 };
+  function writeHl(e, at, st) {
+    st = { ...HL_DEFAULT, ...st };
+    const d = e.dv();
+    d.setUint8(at, { ink: 0, band: 1, both: 2 }[st.mode] ?? 1); d.setUint8(at + 1, st.height === 'ink' ? 1 : 0);
+    d.setUint32(at + 4, rgba(st.ink), true); d.setUint32(at + 8, rgba(st.band), true);
+    d.setFloat32(at + 12, st.padX, true); d.setFloat32(at + 16, st.padY, true); d.setFloat32(at + 20, st.radius, true); d.setFloat32(at + 24, st.seam, true);
+    d.setUint32(at + 28, st.ms, true); d.setInt32(at + 32, st.layer, true);
+    return at;
+  }
+  function readBoxes(e, at, n) {
+    const d = e.dv(), out = new Array(n);
+    for (let i = 0; i < n; i++) { const o = at + i * 32; out[i] = { id: 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), color: d.getUint32(o + 24, true), radius: d.getFloat32(o + 28, true) }; }
+    return out;
+  }
+
+  class QvpPage {
+    constructor(engine, handle) {
+      this.e = engine; this.h = handle;
+      const ex = engine.ex, s = engine.scratch;
+      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);
+      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);
+      this.ops = new Uint8Array(engine.mem.buffer, opsPtr, opsLen).slice();
+      this.pts = new Float32Array(engine.mem.buffer.slice(ptsPtr, ptsPtr + ptsLen * 4));
+      this.table = new Uint32Array(engine.mem.buffer.slice(tabPtr, tabPtr + nPaths * 32));
+      this.paths = null;
+      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.currentLayout = null;
+      this._defaultInk = 0x231f20ff;
+    }
+    free() { this.e.ex.qvp_page_free(this.h); this.h = 0; }
+
+    // ── geometry ──
+    pathFlags(i) { return this.table[i * 8 + 4]; }
+    pathKind(i) { return this.pathFlags(i) & 0xff; }
+    pathMark(i) { return (this.pathFlags(i) >> 8) & 0xff; }
+    pathFamily(i) { return (this.pathFlags(i) >> 16) & 0xff; }
+    pathEvenOdd(i) { return ((this.pathFlags(i) >> 24) & 1) === 1; }
+    pathWord(i) { const w = this.table[i * 8 + 5]; return w === NONE ? -1 : w; }
+    pathLine(i) { return this.table[i * 8 + 6]; }
+    pathCategory(i) { return this.table[i * 8 + 7] & 0xff; }
+    pathNthInWord(i) { return (this.table[i * 8 + 7] >> 8) & 0xff; }
+    pathNthMark(i) { const n = (this.table[i * 8 + 7] >> 16) & 0xff; return n === 0xff ? -1 : n; }
+    buildPaths() {
+      if (this.paths) return this.paths;
+      const t = this.table, ops = this.ops, pts = this.pts, out = new Array(this.nPaths);
+      for (let i = 0; i < this.nPaths; i++) {
+        const p = new Path2D();
+        let o = t[i * 8], oe = o + t[i * 8 + 1], k = t[i * 8 + 2];
+        for (; o < oe; o++) {
+          switch (ops[o]) {
+            case 0: p.moveTo(pts[k], pts[k + 1]); k += 2; break;
+            case 1: p.lineTo(pts[k], pts[k + 1]); k += 2; break;
+            case 2: p.quadraticCurveTo(pts[k], pts[k + 1], pts[k + 2], pts[k + 3]); k += 4; break;
+            case 3: p.bezierCurveTo(pts[k], pts[k + 1], pts[k + 2], pts[k + 3], pts[k + 4], pts[k + 5]); k += 6; break;
+            case 4: p.closePath(); break;
+          }
+        }
+        out[i] = p;
+      }
+      return (this.paths = out);
+    }
+
+    // ── info records ──
+    _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),
+        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) };
+    }
+    _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),
+        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 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),
+        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); }
+    findWord(surah, ayah, word) { const i = this.e.ex.qvp_find_word(this.h, surah, ayah, word); return i < 0 ? -1 : i; }
+    _target(t) {
+      if (typeof t === 'string') t = parseTarget(t);
+      if (t.wordKey) { const i = this.findWord(...t.wordKey); t = i >= 0 ? T.word(i) : T.words([]); }
+      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))); }
+
+    // ── metadata ──
+    surahs() {
+      const ex = this.e.ex, s = this.e.scratch, n = ex.qvp_surahs_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) }); }
+      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) }); }
+      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) }); }
+      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) }); }
+      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) }); }
+      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) }; }
+    /** 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); }
+    ayahLabel(i) { this.e.ex.qvp_ayah_label(this.h, i, this.e.scratch); return this.e.qstr(this.e.scratch); }
+
+    // ── 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);
+      return this.e.qstr(this.e.scratch);
+    }
+    search(query, { form = 'search', mode = 'includes', normalize = true, loose = 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 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 }); }
+      return out;
+    }
+    wordKey(i) { const w = this.words[i]; return `${w.surah}:${w.ayah}:${w.word}`; }
+    /** attach a words sidecar (object or JSON string/bytes); returns words updated */
+    attachWords(sidecar) { const s = typeof sidecar === 'string' ? sidecar : sidecar instanceof Uint8Array ? this.e.td.decode(sidecar) : JSON.stringify(sidecar); const b = this.e.te.encode(s); const p = this.e.ex.qvp_alloc(b.length); new Uint8Array(this.e.mem.buffer, p, b.length).set(b); const n = this.e.ex.qvp_attach_words(this.h, p, b.length); this.e.ex.qvp_dealloc(p, b.length); return n; }
+    hasForm(form) { return !!this.e.ex.qvp_has_form(this.h, FORM[form] ?? 0); }
+    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; }
+    /** 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; }
+
+    // ── layout ──
+    layout(spec) {
+      const ex = this.e.ex, s = this.e.scratch; let 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;
+      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 });
+    }
+    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] }; }
+
+    // ── 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)); }
+    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); }
+    get defaultInk() { return this._defaultInk; }
+    /** {ink, diacritics, dots, waqf, sifr, ayahMark, numeral, headers, marks: {name: colour}, ms} → handle */
+    theme(t) {
+      const d = this.e.dv(), at = this.e.scratch2 + 16384, c = v => (v === undefined || v === null ? 0 : rgba(v));
+      ['ink', 'diacritics', 'dots', 'waqf', 'sifr', 'ayahMark', 'numeral', 'headers'].forEach((k, i) => d.setUint32(at + i * 4, c(t[k]), true));
+      d.setUint32(at + 32, t.ms || 0, true);
+      const pairs = Object.entries(t.marks || {}).flatMap(([m, col]) => [markId(m), rgba(col)]);
+      const mp = pairs.length ? this.e.putU32(Uint32Array.from(pairs), 20480) : 0;
+      d.setUint32(at + 36, mp, true); d.setUint32(at + 40, pairs.length / 2, true);
+      return this.e.ex.qvp_theme(this.h, at);
+    }
+    styleHandles() { const n = this.e.ex.qvp_style_handles(this.h, this.e.scratch, 4096); return Array.from(new Uint32Array(this.e.mem.buffer, this.e.scratch, Math.min(n, 4096))); }
+
+    // ── 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);
+      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); }
+    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)); }
+
+    // ── 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); }
+
+    // ── 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); }
+    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)); }
+    /** 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); }
+    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); }
+    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); }
+  }
+
+  class QvpAtlas {
+    constructor(engine, handle) { this.e = engine; this.h = handle; }
+    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(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; }
+    pageOfSurah(n) { const s = this.surah(n); return s ? s.page : null; }
+    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); }
+    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)); }
+  }
+
+  /**
+   * Canvas2D host renderer. Order: highlight bands → base ink (cached) → styled ink → mask boxes.
+   * Call `page.tick(performance.now())` before `draw` each frame; keep drawing while it returns true.
+   */
+  class CanvasRenderer {
+    constructor(canvas) {
+      this.canvas = canvas; this.ctx = canvas.getContext('2d');
+      this.base = document.createElement('canvas'); this.baseKey = '';
+      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))];
+    }
+    /** 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);
+      let cur = null, col = 0;
+      const flush = () => { if (cur) { c.fillStyle = css(col); c.fill(cur, 'nonzero'); cur = null; } };
+      for (const b of boxes) {
+        if (!cur || b.id !== cur.id || b.color !== col) { flush(); cur = new Path2D(); cur.id = b.id; col = b.color; }
+        if (b.radius > 0) cur.roundRect(b.x0, b.y0, b.x1 - b.x0, b.y1 - b.y0, b.radius); else cur.rect(b.x0, b.y0, b.x1 - b.x0, b.y1 - b.y0);
+      }
+      flush();
+    }
+    draw(page, view, dpr) {
+      const paths = page.buildPaths();
+      const styled = page.styled();
+      const styledSet = new Set(styled.map(s => s[0]));
+      const L = page.currentLayout || { scale: 1, ox: 0, oy: 0, lineDy: null, pitch: 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) {
+        const t0 = performance.now();
+        this.base.width = W; this.base.height = H;
+        const b = this.base.getContext('2d');
+        b.fillStyle = css(ink);
+        let n = 0, cur = -1;
+        for (let i = 0; i < page.nPaths; i++) {
+          if (styledSet.has(i)) continue;
+          const ln = page.pathLine(i); if (ln !== cur) { setTf(b, ln); cur = ln; }
+          b.fill(paths[i], page.pathEvenOdd(i) ? 'evenodd' : 'nonzero'); n++;
+        }
+        this.baseKey = key; this.stats.baseMs = performance.now() - t0; this.stats.basePaths = n;
+      }
+      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();
+      this.drawBoxes(c, bands, view, dpr);
+      c.setTransform(1, 0, 0, 1, 0, 0);
+      c.drawImage(this.base, 0, 0);
+      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; }
+        c.fillStyle = css(col); c.fill(paths[i], page.pathEvenOdd(i) ? 'evenodd' : 'nonzero');
+      }
+      this.drawBoxes(c, page.maskBoxes(), 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 };
+})(typeof window !== 'undefined' ? window : globalThis);