AyahLab user guide

Getting Started

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

• 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, which opens as its own window. Opening it again for another ayah re-points the window you already have.
• Copy to clipboard — the Copy button puts the folio image on your clipboard, ready to paste into a document or a message.
• 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.
• Copy — click the action button to copy the current folio image to the clipboard.
• 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.

Post Cards

Turn a passage into an image worth sharing. Open Create Post Card from the Parchment action bar; the designer opens in its own window, so you can keep reading while you compose.

• Ayah — pick a surah and one ayah or a range (shift-click for a range). The card updates as you select.
• Text — Arabic font, size, colour and line spacing; optional translation, Basmallah header, ayah numbers, and a reference line in English or Arabic. Each layer has its own size and colour, plus an optional drop shadow with blur, offset and opacity.
• Background — a plain colour, one of nine Islamic patterns (eight-point star, rosette, octagon, quatrefoil, girih, lattice, chevron, crosshatch, dot field), a manuscript folio fetched from Corpus Coranicum, or a manuscript and a pattern together. Patterns take their own colour, scale and line weight; folios can be zoomed, offset, blurred or turned greyscale, and you can page through the folios available for the ayah.
• Layout — gradient overlays in a dozen palettes and five directions (top to bottom, bottom to top, left to right, diagonal, radial), with adjustable opacity.
• Export — save a PNG, or copy the card straight to the clipboard.

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 & Typst Documents

Any Lexical document can be exported as either a Microsoft Word .docx file or a Typst .typ document. Word export carries headings, formatting, tables, equations, quotes, and Arabic text into Word, Google Docs, or another word processor. Typst export converts the same content into editable Typst markup for further typesetting and compilation.

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.

Find & Replace

Search the document from the toolbar's Find and replace button. The panel supports match case and whole word, steps through matches with next and previous, and replaces either the current match or all of them at once.

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.

Lean 4 — Proofs

Lean 4 is a proof assistant and programming language. AyahLab treats it like Julia and Typst: a file type with its own editor, and a cell type inside the notebook.

Installing the toolchain

Compiling Lean needs the Lean toolchain. The first time you compile, AyahLab offers to fetch it through elan into the app's own folder — the download runs in the background and your file stays open and editable while it works. If Lean is already on your system, point the app at it in Settings → Lean, where you can also check for and install updates.

The editor and the Infoview

• Infoview — Lean's feedback panel, beside the editor. Errors, warnings and #eval output appear here; filter by severity, and resize the panel to taste.
• Live or manual — in Live mode Lean re-runs when you pause typing. In Manual mode nothing runs until you press Compile or Ctrl/Cmd+Enter.
• Format — tidies trailing whitespace, tabs and blank lines. It deliberately does not re-indent your proof.
• Completions — press Tab to accept a suggestion.

Lean cells in the notebook

Type /lean in a Lexical document to insert a compilable Lean cell, alongside your prose and Julia cells. Compile a single cell or every cell in the document, clear outputs, stop a run in progress, and inspect the active toolchain from the cell toolbar.

Spell Checking

Spelling is checked as you type, in the rich-text editor and in the code editors. The picker in the corner of the editor shows the current language and turns the whole thing on or off.

• Suggestions — click a flagged word for corrections, plus Ignore and Ignore all for words you want left alone.
• Languages — installed dictionaries are listed first; anything else is downloaded on demand from the same menu.
• The picker sits quietly at the bottom-right of the editor and brightens on hover; in Sukūn Mode it stays out of the way until you reach for it.

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 opens as its own OS window, with its own entry in the dock or taskbar, so it can sit beside your reading rather than over it. 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.

Sukūn Mode

Sukūn Mode is AyahLab's distraction-free workspace, similar to Zen Mode in Visual Studio Code. It removes borders and shadows, dims interface icons, and quiets the surrounding UI so you can focus on the Qur'an and your active editor.

Enable it from Editor Tools → Settings. When you need the hidden controls, use the candle button at the center top of the app to briefly reveal the full interface, then return to the calm view.

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 or disable Sukūn Mode.

Privacy

Data Sources

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