quran.sh 0.1.0

package/README.md

@@ -0,0 +1,195 @@
+# 📖 quran.sh
+
+> A fast, offline-first Quran CLI and TUI reader built with Bun and TypeScript
+
+[![npm](https://img.shields.io/npm/v/quran.sh)](https://www.npmjs.com/package/quran.sh)
+[![License](https://img.shields.io/github/license/smashah/quran.sh)](LICENSE)
+
+## Features
+
+### 📚 Reading
+- **Offline-First** — All data bundled, works without internet
+- **Multi-Pane Reader** — Arabic (top), Translation + Transliteration (split below)
+- **10 Languages** — Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese — press `l` to cycle
+- **Arabic Text Shaping** — Proper connected Arabic rendering via `arabic-reshaper`
+- **Verse Flow Modes** — Stacked, inline, or continuous flow — press `F` to cycle
+- **Arabic Layout** — Configurable alignment (`A`) and width (`W`)
+
+### 🎨 Design
+- **12 Dynasty Themes** — Mamluk, Ottoman, Safavid, Andalusian, Maghribi, Madinah, Umayyad, Abbasid, Fatimid, Seljuk, Mughal — each with unique ornaments, borders and color palettes inspired by Islamic manuscript illumination
+- **Light & Dark Mode** — Auto-detection + manual toggle
+- **Themed Progress Bars** — Custom ASCII progress indicators in title bars using dynasty-specific ornament characters
+- **Focus Indicators** — Heavy borders + diamond icon on the focused pane
+
+### 🔖 Study Tools
+- **Bookmarks** — Mark and revisit favorite verses
+- **Cues** — 9 quick-navigation slots (1–9) for instant jumping
+- **Reflections** — Personal notes attached to any verse
+- **Activity Panel** — Toggleable right panel listing all bookmarks, cues, and reflections
+- **Full-Text Search** — Search across all translations with `/`
+- **Command Palette** — Quick access to all commands with `Ctrl+P`
+
+### 📊 Progress Tracking
+- **Reading Mode** — Toggle between browsing (no tracking) and reading (tracks every verse) with `m`
+- **Surah Completion** — When navigating away from a surah in reading mode, prompted to mark it as complete
+- **Reading Stats** — Sidebar widget showing verses read, unique verses, surahs touched, and surahs completed — filterable by Today, Week, Month, All Time, and Session
+- **Streak Tracking** — Current streak, longest streak, and total reading days via CLI
+- **Verse Logging** — Log individual verses or full surahs as read via CLI
+
+### 💾 Persistence
+- **SQLite Database** — All bookmarks, cues, reflections, reading logs, and preferences stored locally
+- **Auto-Restore** — Selected surah, verse position, theme, language, layout, sidebar/panel visibility, and reading mode all persist across sessions
+
+## Installation
+
+```bash
+# Run directly (no install)
+bunx quran.sh
+
+# Global install
+bun install -g quran.sh
+
+# Or with npm
+npm install -g quran.sh
+```
+
+## Usage
+
+### CLI Commands
+
+```bash
+# Launch interactive TUI
+quran
+
+# Read a surah (by number or name)
+quran read 1
+quran read al-fatihah
+
+# Read a specific verse
+quran read 2:255
+
+# Search for verses
+quran search "merciful"
+
+# Log reading progress
+quran log 1
+quran log 2:255
+
+# View reading streak
+quran streak
+```
+
+### TUI Keyboard Shortcuts
+
+#### Navigation
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Cycle focus: Sidebar → Arabic → Translation → Transliteration → Panel |
+| `Shift+Tab` | Cycle sidebar focus: Surah List ↔ Reading Stats |
+| `↑/↓` or `j/k` | Navigate surahs or verses |
+| `Enter` | Select surah (in sidebar) |
+| `1-9` | Jump to cue slot |
+
+#### Pane Toggles
+
+| Key | Action |
+|-----|--------|
+| `a` | Toggle Arabic pane |
+| `t` | Toggle Translation pane |
+| `r` | Toggle Transliteration pane |
+| `s` | Toggle sidebar |
+| `B` | Toggle activity panel (Bookmarks / Cues / Reflections) |
+
+#### Study
+
+| Key | Action |
+|-----|--------|
+| `b` | Toggle bookmark on current verse |
+| `R` | Add/edit reflection |
+| `! to (` | Set cue 1–9 (Shift+1–9) |
+| `/` | Search verses |
+| `m` | Toggle Reading/Browsing mode |
+
+#### Display
+
+| Key | Action |
+|-----|--------|
+| `T` | Cycle dynasty theme |
+| `D` | Cycle light/dark mode |
+| `+`/`-` | Increase/decrease verse spacing |
+| `A` | Cycle Arabic alignment |
+| `W` | Cycle Arabic width |
+| `F` | Cycle verse flow mode |
+
+#### General
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+P` | Open command palette |
+| `?` | Show/hide help dialog |
+| `ESC` | Dismiss dialog / Clear search |
+| `q` | Quit |
+
+## Data Source
+
+- Translations from [quran-json](https://github.com/risan/quran-json)
+- 114 surahs, 6,236 verses
+- 10 languages: Bengali, English, Spanish, French, Indonesian, Russian, Swedish, Turkish, Urdu, Chinese
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/smashah/quran.sh.git
+cd quran.sh
+
+# Install dependencies
+bun install
+
+# Run TUI
+bun run src/index.ts
+
+# Run CLI
+bun run src/index.ts read 1
+
+# Run tests
+bun test
+
+# Build standalone binary
+bun run build
+# → outputs ./dist/quran
+```
+
+## Recording Demos
+
+Demo recording scripts are in `demos/`. To record a TUI demo:
+
+```bash
+# 1. Start a tmux session
+tmux new-session -d -s demo -x 120 -y 35
+
+# 2. Start terminalizer inside it
+tmux send-keys -t demo 'terminalizer record --config demos/tui-demo.yml demos/tui-full -k' Enter
+
+# 3. Run the keystroke automation (in another terminal)
+bash demos/send-keys.sh
+
+# 4. Render to GIF
+terminalizer render demos/tui-full
+```
+
+## License
+
+MIT © smashah
+
+## Credits
+
+- Built with [Bun](https://bun.sh)
+- UI powered by [OpenTUI](https://github.com/nicktomlin/opentui)
+- Arabic shaping via [arabic-reshaper](https://github.com/a-patel/arabic-reshaper)
+- Data from [quran-json](https://github.com/risan/quran-json)
+
+---
+
+Made with ❤️ for the Muslim community

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "quran.sh",
+  "version": "0.1.0",
+  "description": "A fast, offline-first Quran CLI and TUI reader",
+  "module": "src/index.ts",
+  "type": "module",
+  "bin": {
+    "quran": "./dist/quran"
+  },
+  "keywords": [
+    "quran",
+    "islam",
+    "cli",
+    "tui",
+    "terminal",
+    "reader"
+  ],
+  "author": "smashah",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/smashah/quran.sh.git"
+  },
+  "bugs": "https://github.com/smashah/quran.sh/issues",
+  "homepage": "https://github.com/smashah/quran.sh",
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build --compile --minify --sourcemap --format esm ./src/index.ts --outfile ./dist/quran"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@opentui/core": "^0.1.77",
+    "@opentui/react": "^0.1.77",
+    "arabic-reshaper": "^1.1.0",
+    "bidi-js": "^1.0.3",
+    "quran-json": "^3.1.2",
+    "react": "^19.0.0",
+    "yoga-layout": "^3.2.1"
+  }
+}