AyahLab user guide

Getting Started

AyahLab has a two-panel layout: the Qur'an Reader on the left and the Editor Panel on the right.

• A chevron button on the divider collapses or expands the editor panel.
• Surah Controls widget floats in the bottom-right corner — click it to expand the control card.
• Editor Tools widget floats in the bottom-left corner — click it to access file management and app settings.

The Qur'an Reader

The reader displays the full Qur'an with morphological annotations on every word.

• Click any Arabic word to open its morphology popover — shows root, lemma, part of speech, and full grammar details.
• Use Prev / Next buttons at the bottom edge to navigate between surahs.
• Font size and family are adjustable via the Surah Controls widget.

Morphology Popover Actions

• Insert to Lexical (＋ square icon) — inserts the word's full morphology as a formatted table into the active Lexical editor tab.
• Highlight with note (magic wand icon) — opens the Highlight dialog to save the word with a colour tag and optional note.
• Pin (pin icon) — locks the popover open so it stays on screen when you click other words.
• Close (✕) — dismisses the popover. Clicking outside also closes it unless pinned.

Buckwalter Script

The Buckwalter transliteration scheme represents Arabic letters and diacritics using ASCII characters. It is used in the Quranic Arabic Corpus for morphological annotation.

Consonants

Diacritics (Harakat)

Manuscript Viewer

Browse high-resolution images of early Qur'anic manuscripts sourced from the Corpus Coranicum project (Berlin-Brandenburg Academy of Sciences).

• Opening the viewer — hover any ayah number in the reader. A scroll icon appears. Click it to open the Manuscript Viewer.
• Manuscript list — the left rail lists all manuscripts containing the selected ayah, sorted by estimated date.
• Folio tabs — when a manuscript has multiple folios covering the ayah, tab buttons let you switch between them.
• Metadata panel — below the image, a grid shows date, radiocarbon dating, writing surface, script style, dimensions, and more.
• In-panel zoom — use ＋ / − buttons or scroll the mouse wheel to zoom up to 8×. Drag to pan when zoomed in.
• Fullscreen — click the fullscreen icon to expand to a dark overlay. Press Escape to exit.
• Download — click "Download full" to save a high-resolution version of the current folio.
• Insert to Lexical — click the action button to embed the current folio image into the active Lexical editor.
• Images are cached — thumbnails are stored locally for instant re-access.
• Open as a separate window — launch the Manuscript Viewer in its own standalone window (also reachable from the Manuscript icon in the reader's action bar) for focused study beside the Qur'an.
• Session persistence — the viewer remembers the last manuscript you had open during your session.

Reader Actions

Four action buttons appear above the reader when hovering the top edge:

• Bookmark (bookmark icon) — save any ayah with an optional note; jump back anytime from the bookmarks list.
• Highlight (magic stick icon) — select Arabic text in the reader, then click "Save Highlight" in the popup.
• Search (magnifier icon) — searches Arabic text or translation. A translator must be selected in Surah Controls for translation search to work.
  You can also jump directly to a specific ayah by typing <surah>:<ayah> into the search field — for example, 2:255 opens Surah 2, ayah 255 (Āyat al-Kursī). The same shorthand works for any surah:ayah pair.
• Manuscript (gallery icon) — open the Manuscript lookup directly from the reader. Enter a surah number and an ayah number (e.g. surah 2, ayah 255) and AyahLab fetches the matching manuscript folios from Corpus Coranicum — sorted by date, with zoom and download available in the Manuscript Viewer.

Recitation Player

To enable audio playback, open Surah Controls and select a reciter. The player appears at the bottom of the reader.

• Tap play / pause, or skip forward / back by ayah.
• Download a surah for offline use via the download icon.
• After a search, the player switches to playlist mode — cycling through all matched ayahs automatically.

Choosing Reciters

The player supports two reciter slots, which you can fill from a roster of five reciters. Click the manage reciters button (person icon) to open the Reciter Select dialog, then pick any two to display in the recitation player:

• Abdul-Basit Abdul-Samad
• Maher Al-Muaiqly
• Mishari Rashid Al-Afasy
• Saad Al-Ghamdi
• Yasser Al-Dosari

Mini Player

When you hide the surah page (from Surah Controls), the main player tucks away but playback keeps going — a small floating pill appears so you stay in control while you read or work elsewhere.

• Holds the essentials: play / pause, skip to the previous or next ayah, and a live ayah counter (which shows your position in the playlist after a search).
• Drag it anywhere by the book-icon handle; it starts near the bottom-right corner and stays where you leave it.
• Close it with the × and audio keeps playing. The pill returns the next time you hide the surah page.

Surah & Translation Controls

Click the bottom-right widget to expand the control card:

• Surah picker — scrollable list of all 114 surahs.
• Font — choose Scheherazade New or Amiri Quran; sizes Small / Medium / Large.
• Translator — choose from more than 30 translations across multiple languages; your choice persists across sessions.
• WBW (Word-by-Word) — shows the meaning of each word beneath the Arabic, now in multiple languages (English plus Bengali, French, Hindi, Indonesian, Persian, Tamil, Turkish, and Urdu). You can also look up the meaning of any single selected word on demand.
• Transliteration — shows romanized pronunciation under each word.
• Hide Reader toggle — collapses the Qur'an pane to give the editor full width.

The Editor Panel

A multi-tab workspace. Create tabs via Editor Tools → New File, then choose Lexical, Typst, or Julia.

• Tabs are persistent — your work is saved automatically.
• The sidebar collapses with the chevron button on the divider.
• Tabs show an italic title in "preview" mode (single-click to open). Double-click to pin a tab permanently.
• Right-click a tab for Close, Close Others, Close Right, and Close Left actions.

Split & Triple-Split View

Pair two editors side by side, or open a triple-split of three editors at once for Julia and Typst workflows — reference, write, and run in parallel. Drag one tab onto another to create a split.

Lexical — Rich Text & Julia Notebooks

A rich text editor for free-form study notes and commentary — and a Julia notebook environment in the same surface, so prose and executable code cells can live in the same document.

• Supports headings, bold, italic, bullet lists, numbered lists, and inline links.
• Julia notebook mode — interleave executable Julia code cells with prose for reproducible analyses that can drive the Qur'an reader live (see the Julia section for the AL.* API).
• Ideal for capturing translations, research notes, or personal commentary alongside the reader.

A /julia cell runs in its own runtime, separate from the standalone Julia editor (so the two never conflict), and can render interactive output inline — including 3D graphs from PlotlyJS.jl and interactive plots from Gadfly.jl.

Slash Commands

Type / on an empty line to open the command menu, then keep typing to filter. The available commands are:

• /math — insert an inline math (LaTeX) expression.
• /math-block — insert a centered, full-width math block.
• /quote — insert a block quote.
• /table — insert a table.
• /check — insert a check list (interactive to-do items).
• /q-<surah>-<ayah> — paste a Qur'an ayah inline (for example, /q-2-255 inserts Surah 2, ayah 255). Ranges and lists are supported, e.g. /q-2-[1:5].
• /qt-<surah>-<ayah> — paste a Qur'an ayah's translation inline (for example, /qt-2-255), using the translation currently selected in Surah Controls. It accepts the same surah, ayah, range, and list syntax as /q.
• /julia — insert an executable Julia code cell (see Julia notebook mode above).
• /cite — insert a citation from your reference library (see References & Citations below).

Arabic Phrase Shortcuts

A family of /s commands inserts commonly used Arabic honorifics and devotional phrases instantly — fully formed and automatically set in the Scheherazade New font. Type /s to open the list, then keep typing to filter it. The available shortcuts are:

• /s-saw — صلى الله عليه وسلم (ṣallā Allāhu ʿalayhi wa sallam)
• /s-rd — رضي الله عنه (raḍiya Allāhu ʿanhu, r.a.). /s-rha and /s-rhm give the feminine (عنها) and plural (عنهم) forms.
• /s-as — عليه السلام (ʿalayhi as-salām); /s-aha for عليها السلام.
• /s-god — الله (Allāh).
• /s-swt — سبحانه وتعالى (subḥānahu wa taʿālā).
• /s-azza — عز وجل (ʿazza wa jall); /s-jj for جل جلاله.
• /s-rh — رحمه الله (raḥimahu Allāh).
• /s-bmh — بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ (Bismillāh ar-Raḥmān ar-Raḥīm).
• /s-isa (إن شاء الله), /s-msa (ما شاء الله), /s-alh (الحمد لله), /s-sub (سبحان الله), /s-akb (الله أكبر), and /s-tah (لا إله إلا الله).
• /s-jzk (جزاك الله خيرا), /s-bfk (بارك الله فيك), /s-stg (أستغفر الله), /s-slm (السلام عليكم ورحمة الله وبركاته), /s-inna (إنا لله وإنا إليه راجعون), and /s-hsb (حسبنا الله ونعم الوكيل).

For the most common honorifics there is also a parallel /sc family that inserts the dedicated compressed single-glyph Unicode ligatures:

• /sc-saw — ﷺ
• /sc-jj — ﷻ
• /sc-bmh — ﷽
• /sc-god — ﷲ

References & Citations

Open the References panel from the editor toolbar to build a citation library for your document. It is a floating panel you can drag by its header and resize from any edge or corner. There are three ways to add references:

• Paste — paste raw BibTeX (.bib) or RIS (.ris) content and click Add to library.
• Import files — pick one or more .bib / .ris files, or point AyahLab at a folder and it scans every .bib / .ris file inside.
• Search by ID — enter one or more DOI, PMID, ISBN, or arXiv identifiers (one per line). AyahLab auto-detects the type of each and fetches the full reference metadata online.

Each reference appears as a card showing its author, title, source, and identifier. From a card you can Copy a formatted citation or copy its cite key — the short code name used to cite it in Typst. A filter box narrows a long library by author, title, year, or identifier, and the collapse toggle in the header hides the add-reference area to give the list the full panel height.

Use Save as .bib to export your library to a BibTeX file, Load file to bring one back in, or Clear all to start over.

To cite while writing, type /cite in the editor to open a searchable list of your references and pick one to insert. Cited works are collected automatically into a References section at the end of the document; double-click that section to choose a citation style, or double-click an inline citation to edit it. If a reference is later removed from your library, any citation pointing to it is flagged so you can fix it.

Export to Microsoft Word

Any Lexical document can be exported to a Microsoft Word .docx file. Headings, formatting, tables, equations, quotes, and Arabic text carry across, so you can take your work out of AyahLab and into Word, Google Docs, or any word processor for sharing and submission.

Custom Fonts

Assign your own preferred font to the Lexical editor (as well as the Tafsir and Translation dialogs) so you can read and write in the typeface that suits you best.

Typst — Professional Publishing

A markup-based typesetting language with live preview. Write source in the editor; the rendered document updates in real time.

• Any @preview package used in an #import statement is downloaded automatically from the Typst Universe registry on first use and cached locally.
• Great for structured papers, formatted essays, and printable documents.

Julia — Scientific Computing

AyahLab includes a full Julia terminal — a live coding environment you can use to navigate the Qur'an reader, run calculations, and build data-driven analyses.

• Install Julia via Editor Tools → Julia → Auto-install (or point to an existing binary in Settings).
• Once started, type any command into the terminal and press Enter to run it.

AL.surah() — Navigate to a Surah

Type AL.surah(n) and press Enter — the Qur'an reader immediately jumps to that surah.

AL.ayah() — Navigate to a Specific Ayah

AL.ayah() takes a surah reference and an ayah number.

Going Further — Loops & Patterns

Because Julia is a full programming language, you can use variables and loops.

Built-in Terminal

AyahLab includes a full integrated terminal so you can run commands and drive your tooling without leaving the app. You can also search within the terminal output, making long sessions easy to navigate.

Editor Themes & Power Features

The Julia and Typst code editors are now closer to a full IDE:

• Improved syntax highlighting for both Julia and Typst.
• Four new editor themes to choose from in the editor settings.
• Go to definition — click a symbol to jump to where it is defined within the file.
• Run the complete function even when the cursor sits at its last line.
• Variable memory — the editor remembers variables you have defined in the file so autocomplete can suggest them.

AI Selection Toolbar

Select any text in an editor and a small floating toolbar appears just above the selection. It offers quick AI rewrites that replace the selected text in place, plus a shortcut to ask the AI about it. AI features are part of the Pro plan.

The toolbar is context-aware — it automatically adapts to whatever you are working on, and it is not limited to the editor. It also appears inside the Morphology view, the Tafsir, and the Manuscript viewer, so you can ask about an ayah, a word's grammar, a tafsir passage, or a manuscript without assembling any context yourself.

Rewrite Actions

Each of these runs on the selection and swaps in the result when it finishes — a spinner shows on the button while it works:

• Paraphrase (pen icon) — rewrites the passage in different words while keeping the meaning.
• Elaborate (expand icon) — expands the selection with more detail.
• Shorten (contract icon) — condenses the selection into something tighter.
• Prompt (magic wand icon) — opens a small input where you type your own instruction (for example, "translate to formal Arabic" or "fix the grammar"). Press Enter to run it.

Select code in a Julia cell and the same toolbar acts as a coding assistant — it adjusts to the active workspace automatically.

Ask AI

The Ask AI button (chat icon) does not edit your text. Instead it opens a small prompt where you type a question about the selection — when you submit, the selected text and your question are handed to the AI Chat window as a new conversation, so you can keep the discussion going there.

AI Chat

AI Chat is a free-floating conversation window you can drag anywhere on screen and resize from any edge or corner. Ask questions, work through ideas, or follow up on a passage you sent over with Ask AI. It is a Pro feature.

Sending Messages

• Type in the box and press Enter to send; Shift + Enter inserts a new line.
• Replies stream in live. Use the Stop button to halt a response mid-generation.
• Answers render full Markdown — including headings, lists, tables, code blocks with syntax highlighting, and LaTeX math.
• Each reply has a Copy button to grab its text.
• Drag the splitter above the input box to make the typing area taller or shorter.

Standard vs Advanced Model

A toggle above the input switches between two model classes:

• Standard — fast and efficient, the best choice for everyday questions.
• Advanced — frontier reasoning for harder problems. It draws on your premium quota.

Conversations & Storage

• The sidebar lists your saved conversations. Start a fresh one with New chat, click any chat to reopen it, or delete one you no longer need. Toggle the sidebar from the header to give the thread more room.
• A storage meter shows how much of your saved-chat space is in use. Banners warn you as you near the limit, and you'll be prompted when a token or storage quota is reached.

Encrypted History

Your chat history is protected by a passphrase you choose. The first time you open AI Chat you set an encryption passphrase; afterwards you unlock with it to read your past conversations. The lock button in the header re-locks the history at any time.

Take-Home Message

The Take-Home Message (lightbulb icon on the reader) turns the ayah, or ayahs, you are currently studying into a short personal-growth reflection. It reads the verses shown in the Morphology view, so there is no context to assemble — just open it and generate. It is a Pro feature.

The reflection is organised into clear cards:

• Key lessons — the core teachings of the passage.
• Practical steps — concrete actions to put them into practice.
• Reflection prompts — questions to sit with.
• Daily-life applications — where the lesson shows up day to day.
• Take-home message — the payoff, in a single highlighted card.

Ayah references in the text appear as clickable chips (for example, ﴾2:255﴿) — tap one to scroll to that verse in the reader and briefly highlight it. The whole reflection follows the app's display language, including right-to-left layouts.

Generating & Regenerating

• Generation runs only when you press Generate — opening the dialog never spends tokens on its own.
• The last message is kept for the session, so reopening the dialog is instant.
• If the ayahs on screen change after a message is made, a banner notes it is out of date and offers to regenerate for the new selection.
• A Standard / Advanced model toggle sits in the footer. Advanced draws on your premium quota; if that runs out, you can drop back to Standard and try again in one click.

Settings & Tour

Open Editor Tools → Settings to:

• Restart the onboarding tour from step 1.
• Toggle Light / Dark mode.
• Re-open the Help panel.
• Toggle the Manuscript Viewer on or off, and clear the local image cache.
• Scale the interface (accessibility) — a UI scaling setting enlarges text and controls across the app for easier reading.
• Adjust the editor page width — set the Lexical editor's width to your liking; it can be tuned via the page width option in the editor toolbar whether or not the Qur'an pane is hidden.
• Enable Sukūn Mode — a distraction-free styling that hides toolbars, sidebars, and chrome so only the Qur'an and your active editor remain on screen. While in Sukūn Mode, the otherwise hidden buttons can be reached from the candle button at the center top of the app — click it to reveal the controls, click again (or move away) to return to the calm view.

Privacy

Data Sources

AyahLab is built on open, scholarly datasets. All data is bundled locally with the app.