khatt 0.1.0__tar.gz

khatt-0.1.0/.gitattributes

@@ -0,0 +1,9 @@
+# Normalize all text files to LF in the repo and working tree.
+# Golden test snapshots must be byte-identical across platforms.
+* text=auto eol=lf
+
+# Binary assets
+*.ttf binary
+*.otf binary
+*.png binary
+*.gif binary

khatt-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: py${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    env:
+      PYTHONUTF8: "1"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint (ruff check)
+        run: uv run ruff check .
+
+      - name: Format check (ruff format)
+        run: uv run ruff format --check .
+
+      - name: Type check (mypy)
+        run: uv run mypy khatt
+
+      - name: Tests (pytest + coverage)
+        run: uv run pytest

khatt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+# PyPI release via trusted publishing (OIDC — no API tokens).
+#
+# Fires when a v* tag is pushed, or on a manual dispatch from the Actions tab.
+# Requires a trusted publisher to be configured for the khatt project on PyPI
+# (Account → Publishing): owner DrEssam97, repo khatt, workflow release.yml,
+# environment pypi.
+
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # trusted publishing (OIDC), no API token needed
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

khatt-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+.venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Local tooling
+.claude/
+
+# Editors / OS
+.idea/
+.vscode/
+*.swp
+Thumbs.db
+.DS_Store
+
+# Gradio
+.gradio/
+flagged/

khatt-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^khatt/fonts/LICENSES/
+      - id: end-of-file-fixer
+        exclude: ^khatt/fonts/LICENSES/
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.21
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: uv-lock-check
+        name: uv lock --check
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$

khatt-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

khatt-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-11
+
+### Added
+
+- **Engine A — rasterize-then-map rendering pipeline**: HarfBuzz shaping
+  (`uharfbuzz` + `python-bidi`) → FreeType rasterization (`freetype-py`) →
+  density mapping to character ramps.
+- Correct Arabic shaping: positional forms, the mandatory لا ligature, mixed
+  Arabic/Latin/digit visual ordering, and a `keep_tashkeel` flag (diacritics
+  are stripped by default).
+- Three output styles: `blocks` (░▒▓█), `ascii` (density ramp), `braille`
+  (2×4 dot patterns), all with an optional coverage `threshold`.
+- Four bundled OFL fonts: Amiri (default), Cairo, Noto Naskh Arabic, Rubik,
+  with license texts preserved under `khatt/fonts/LICENSES/`.
+- Public API: `khatt.render(text, font, style, width, threshold,
+  keep_tashkeel)`, `khatt.list_fonts()`, `khatt.list_styles()`.
+- `khatt` CLI (typer): `--font/--style/--width/--threshold/--keep-tashkeel`,
+  `--list-fonts`, `--list-styles`, `--output` (text art or PNG of the
+  rendered text), stdin input, UTF-8 output on Windows consoles.
+- Single-file Gradio app (`app.py`) with live preview, deployable unchanged
+  to a Hugging Face Space (`[app]` extra).
+- Golden-file snapshot tests with a `pytest --update-golden` refresh flow;
+  83-test suite at ≥85% enforced coverage on a 3.10–3.13 × Ubuntu/Windows
+  CI matrix.
+
+[0.1.0]: https://github.com/DrEssam97/khatt/releases/tag/v0.1.0

khatt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to Khatt
+
+Thanks for helping! This is a small project with strict hygiene — the rules below keep
+it that way.
+
+## Setup
+
+```bash
+git clone https://github.com/DrEssam97/khatt.git && cd khatt
+uv sync --all-extras       # runtime + dev + gradio
+uv run pre-commit install
+```
+
+Python 3.10–3.13 are supported; local development is pinned to 3.13 via
+`.python-version`. Everything runs through [uv](https://docs.astral.sh/uv/) — there is
+no `requirements-dev.txt` and no manual venv management.
+
+## Workflow
+
+- **Never commit to `main`.** Branch per change: `feat/…`, `fix/…`, `test/…`,
+  `docs/…`, `ci/…`, `chore/…`.
+- **Conventional Commits** for every message: `feat: …`, `fix: …`, `test: …`, etc.
+- Before every merge/push, the full gate must be green:
+
+  ```bash
+  uv run ruff check .
+  uv run ruff format --check .
+  uv run mypy khatt
+  uv run pytest
+  ```
+
+- Coverage must stay ≥ 85% (enforced by pytest's `--cov-fail-under`).
+
+## Tests
+
+Write tests **with** the feature, not after. Shaping assertions are glyph-ID
+relational (the bundled font builds have no `post` name table) — see
+`tests/test_shaping.py` for the pattern.
+
+If you intentionally change rendering output, regenerate the golden snapshots and
+commit the resulting diff — reviewers judge the art change from it:
+
+```bash
+uv run pytest --update-golden
+```
+
+## Fonts
+
+Bundled fonts must be OFL-licensed, with the complete license text added under
+`khatt/fonts/LICENSES/` (that directory is excluded from whitespace-normalization
+hooks — license texts stay verbatim). Register new fonts in
+`khatt/fonts/__init__.py`.
+
+## Scope
+
+v0.1.x is Engine A (rasterize-then-map) only. Hand-drawn FIGlet-style connected
+Arabic fonts (Engine B), ANSI color, animation, and image-to-ASCII are out of scope —
+see [ROADMAP.md](ROADMAP.md) before proposing features.

khatt-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 Mohammed Essam
+
+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.
+
+---
+
+The Arabic fonts bundled under khatt/fonts/ are NOT covered by this license.
+They are licensed under the SIL Open Font License (OFL) 1.1; the full license
+text for each font family is preserved in khatt/fonts/LICENSES/.

khatt-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: khatt
+Version: 0.1.0
+Summary: Render Arabic text as ASCII/Unicode-block art — the Arabic FIGlet
+Project-URL: Homepage, https://github.com/DrEssam97/khatt
+Project-URL: Repository, https://github.com/DrEssam97/khatt
+Project-URL: Issues, https://github.com/DrEssam97/khatt/issues
+Project-URL: Changelog, https://github.com/DrEssam97/khatt/blob/main/CHANGELOG.md
+Author-email: Mohammed Essam <mohammedessam613@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: arabic,ascii-art,figlet,harfbuzz,rtl,text-art,unicode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: Arabic
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Artistic Software
+Classifier: Topic :: Text Processing :: Fonts
+Requires-Python: >=3.10
+Requires-Dist: freetype-py>=2.5.1
+Requires-Dist: pillow>=12.3.0
+Requires-Dist: python-bidi>=0.6.11
+Requires-Dist: typer>=0.26.8
+Requires-Dist: uharfbuzz>=0.55.0
+Provides-Extra: app
+Requires-Dist: gradio>=6.20.0; extra == 'app'
+Description-Content-Type: text/markdown
+
+# خَطّ — Khatt
+
+[![CI](https://github.com/DrEssam97/khatt/actions/workflows/ci.yml/badge.svg)](https://github.com/DrEssam97/khatt/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](pyproject.toml)
+[![Fonts: OFL](https://img.shields.io/badge/fonts-SIL%20OFL%201.1-lightgrey.svg)](khatt/fonts/LICENSES/)
+
+**Render Arabic text as ASCII/Unicode-block art — the Arabic FIGlet that FIGlet can't be.**
+
+```text
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⡄
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢺⣿⣿⣄
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⠟
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢻⣿⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣤⣄⡀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⣿⣿⡗
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠛⢿⣿⠟
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⣀⣠⣄⣀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⡏⠀⠀⠀⠀⣀⣤⣶⣿⣿⣿⣿⣿⣷⡄⠀⠀⠀⠀⣠⣶⣿⣿⣷⣶⣤⣄⣀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⠇⠀⣀⣴⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⢠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣶⣦⣤⣀⣀
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣤⣾⣿⠟⠋⠉⠀⠀⠀⠀⠙⢿⣿⣿⡟⠀⠀⠘⠉⠉⠉⠉⠉⠉⠙⠛⠿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⣶⣶⣶⣶⣶⡶
+⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣿⠟⠋⠀⠀⠀⠀⠀⠀⣀⣠⣤⣶⣿⡿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣤⣽⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠁
+⣀⣀⣀⣀⡀⠀⣀⣀⣀⣴⣿⣿⣥⣤⣤⣤⣴⣶⣶⣿⣿⣿⣿⣿⣿⣋⣀⡀⠀⠀⣀⣀⣀⣀⣤⣤⣶⣾⣿⣿⣿⡿⠿⠛⠋⠉⠁⠀⠀⠀⠀⠀⠀⠈
+⠈⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠟⠋⠉
+⠀⠀⠙⠿⢿⣿⣿⣿⣿⣿⣿⣿⣿⠿⠿⠿⠿⠿⠛⠛⠉⠛⠛⠻⠿⠿⠿⠿⠿⠿⠿⠿⠟⠛⠉⠁
+```
+
+*(that's «خط» — "khatt", meaning line/script/calligraphy — Amiri font, `braille` style)*
+
+```text
+                              -%+.
+       :@.           =:       *+--  =@   *#                       =@
+       -@.           +:        +=   =@   #%                       +@
+   %+  -@.   =%   =**+***:     @#   =@   *%       -*****%+   -%.  +@
+   @*  -@.   +@         +@.    %*   =@   *%      -@-    @*   -@.  +@
+   @+  -@.   +@         .@-    %*   =@   *%      +@     @*   -@.  +@
+   @+  -@.   +@         :@-    %#   =@   #%      :@-    @*   -@.  +@
+   @*  :%****##**********%: +**%#***#%   +#       -*****%#**+*%   =%
+  .@=        :-                                             :- -.
++*%+         -*                                             =+ *:
+```
+
+*(«ايه الأخبار» — "What's the news?" — Cairo font, `ascii` style)*
+
+## Why FIGlet can't do this
+
+FIGlet fonts map **one character to one fixed glyph**. Arabic doesn't work that way:
+
+- Every letter has up to four **positional forms** (isolated / initial / medial / final).
+- Some letter pairs form **mandatory ligatures** — ل + ا must become لا.
+- The script is **cursive**: letters connect, and the connections carry the word's shape.
+- Text runs **right-to-left**, and real text mixes RTL words with LTR numbers and names.
+
+Khatt sidesteps glyph tables entirely with a **rasterize-then-map** pipeline:
+
+```
+text ──► HarfBuzz shaping ──► FreeType rasterization ──► density mapping ──► art
+         (positional forms,    (real Arabic fonts,        (blocks / ascii /
+          ligatures, bidi)      hi-res grayscale)          braille ramps)
+```
+
+The result is genuine calligraphic letterforms — from real fonts — approximated in
+terminal characters.
+
+## Install
+
+```bash
+pip install khatt        # or: uv add khatt
+```
+
+From source:
+
+```bash
+git clone https://github.com/DrEssam97/khatt.git && cd khatt
+uv sync
+```
+
+## Quickstart
+
+### Python API
+
+```python
+import khatt
+
+print(khatt.render("مرحبا"))                          # blocks style, 80 columns
+print(khatt.render("خط", style="braille", width=60))  # high effective resolution
+print(khatt.render("القاهرة", font="cairo", style="ascii", threshold=0.4))
+
+khatt.list_fonts()   # ['amiri', 'cairo', 'noto-naskh', 'rubik']
+khatt.list_styles()  # ['ascii', 'blocks', 'braille']
+```
+
+### CLI
+
+```bash
+khatt "مرحبا"                          # render to the terminal
+khatt "خط" --style braille --width 60
+khatt "القاهرة" -f cairo -s ascii -t 0.4
+echo "سلام" | khatt                    # stdin
+khatt "خط" --output art.txt            # save the art
+khatt "خط" --output khatt.png          # save the rendered text as an image
+khatt --list-fonts
+khatt --list-styles
+```
+
+Arabic diacritics (tashkeel) are stripped by default — they're illegible at
+character-grid resolution. Pass `--keep-tashkeel` (API: `keep_tashkeel=True`) to
+render them.
+
+### Gradio app
+
+```bash
+uv sync --extra app
+uv run python app.py
+```
+
+## Bundled fonts and styles
+
+| Font | Family | Character |
+|---|---|---|
+| `amiri` (default) | Amiri | Classical naskh, rich calligraphic detail |
+| `cairo` | Cairo | Geometric, modern, bold strokes |
+| `noto-naskh` | Noto Naskh Arabic | Clean, highly legible naskh |
+| `rubik` | Rubik | Strong Latin + Arabic pairing for mixed text |
+
+All fonts are licensed under the SIL Open Font License 1.1, preserved verbatim in
+[`khatt/fonts/LICENSES/`](khatt/fonts/LICENSES/).
+
+| Style | Ramp | Notes |
+|---|---|---|
+| `blocks` | `░ ▒ ▓ █` | Default; reads well at any size |
+| `ascii` | `. : - = + * # % @` | Pure ASCII, maximum compatibility |
+| `braille` | `⠁ … ⣿` | 2×4 dots per cell — 8× the effective resolution |
+
+## Deploy the app to a Hugging Face Space
+
+`app.py` follows the Spaces convention (single file at the repo root), so the whole
+repository deploys unchanged with one command:
+
+```bash
+uv run --extra app gradio deploy
+```
+
+This prompts for a Space name on first run (it uses your `huggingface-cli login`
+credentials) and pushes the repo as a Gradio-SDK Space. Alternatively, create a Gradio
+Space on huggingface.co and `git push` this repository to it — `app.py` is picked up
+automatically and dependencies install via `requirements.txt` (which just points at
+`pyproject.toml`).
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pre-commit install
+```
+
+The gate that must be green before every merge:
+
+```bash
+uv run ruff check . && uv run ruff format --check . && uv run mypy khatt && uv run pytest
+```
+
+Rendering changed intentionally? Regenerate the golden snapshots and commit the diff:
+
+```bash
+uv run pytest --update-golden
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), [PLAN.md](PLAN.md) and [ROADMAP.md](ROADMAP.md).
+
+## License
+
+MIT for the code — see [LICENSE](LICENSE). Bundled fonts are under the SIL Open Font
+License 1.1 — see [`khatt/fonts/LICENSES/`](khatt/fonts/LICENSES/).

khatt-0.1.0/PLAN.md

@@ -0,0 +1,125 @@
+# PLAN — Khatt (خَطّ) v0.1.0
+
+> Approved implementation plan for v0.1.0. Decisions settled during planning:
+> **rasterization = uharfbuzz + freetype-py** (freetype-py approved as the one dependency
+> beyond the original spec), and **local-only git for now** (full GitHub Flow discipline
+> kept locally; remote/PRs activate when a GitHub remote is connected).
+
+## Context
+
+Arabic has no FIGlet equivalent: FIGlet's per-character glyph model can't express contextual shaping (isolated/initial/medial/final forms), mandatory ligatures (لا), cursive joining, or RTL. Khatt sidesteps FIGlet entirely with a **rasterize-then-map** pipeline: shape the text properly with a real shaping engine, render it to a bitmap with a real Arabic font, then map pixel density onto character ramps. Deliverables for v0.1.0: a Python library (`khatt.render`), a `khatt` CLI, and a single-file Gradio app deployable to a Hugging Face Space.
+
+## Architecture
+
+```
+text ──► shaping.py ──► raster.py ──► mapper.py ──► str
+        (HarfBuzz:      (FreeType     (density →
+         bidi runs,      glyph        ramp chars:
+         positional      bitmaps →    blocks/ascii/
+         forms,          hi-res PIL   braille)
+         ligatures)      grayscale →
+                         downsample
+                         to grid)
+```
+
+1. **`khatt/shaping.py`** — `python-bidi` splits mixed-direction text into visual-order runs; each run is shaped with `uharfbuzz` (Arabic runs RTL + `language="ar"`, Latin/digit runs LTR). Output: `list[ShapedGlyph]` — dataclass with `gid`, `glyph_name`, `cluster`, `x_advance/y_advance`, `x_offset/y_offset`. Glyph names (e.g. Amiri's `uni0645.init`) are what the shaping tests assert against. A documented `tashkeel` flag controls whether diacritics are kept or stripped before shaping (proposed default: **strip**, because tashkeel is illegible at character-grid resolution; `--keep-tashkeel` to override — see Open Questions).
+2. **`khatt/raster.py`** — `freetype-py` renders each shaped glyph's bitmap at the HarfBuzz-computed pen positions onto a high-resolution Pillow grayscale canvas (hinting disabled, fixed integer ppem → deterministic). The canvas is auto-cropped to ink extents then downsampled with LANCZOS to the target grid: `(width, rows)` cells for blocks/ascii, `(width*2, rows*4)` dots for braille. Rows derive from the ink aspect ratio corrected by a terminal cell aspect of ~0.5 (cells are twice as tall as wide). Determinism note: `freetype-py` wheels bundle their own libfreetype and `uv.lock` pins the version, so output is byte-identical across Ubuntu/Windows — this is what makes golden tests viable on both CI runners.
+3. **`khatt/mapper.py`** — named styles registry: `blocks` (` ░▒▓█`), `ascii` (` .:-=+*#%@`), `braille` (U+2800 + 8-dot bitmask per 2×4 pixel block). `threshold: float | None` in [0,1]: pixels below it are forced blank; ramp mapping over the remaining range (documented, monotonic: darker → denser).
+4. **`khatt/fonts/`** — bundled OFL fonts + registry (`khatt/fonts/__init__.py` maps name → path): **Amiri** (default, naskh, rich ligatures), **Cairo** (geometric kufi-ish, bold weights rasterize well at low res), **Noto Naskh Arabic**, **Rubik** (Arabic + Latin coverage for mixed text). Full OFL texts preserved in `khatt/fonts/LICENSES/`.
+5. **`khatt/__init__.py`** — public API exactly as specced: `render(text, font="amiri", style="blocks", width=80, threshold=None) -> str`, plus `list_fonts()`, `list_styles()`, `__version__`. Ships `py.typed`.
+6. **`khatt/cli.py`** — `typer` app, entry point `khatt` via `[project.scripts]`. Flags: `--font/-f`, `--style/-s`, `--width/-w`, `--threshold/-t`, `--list-fonts`, `--list-styles`, `--output FILE` (`.txt` writes text; `.png` renders the text art string to an image via Pillow), reads stdin when no arg or arg is `-`. Windows UTF-8: `sys.stdout.reconfigure(encoding="utf-8")` (+ same for stderr) before any output.
+7. **`app.py`** (repo root, single file, HF Spaces convention) — Gradio Blocks: RTL textbox (`rtl=True`), font/style dropdowns, width + threshold sliders, live monospace preview (`gr.Code`/styled `gr.Textbox`), copy button, PNG download (`gr.File`). README gets a "Deploy to HF Spaces" section (one command via `huggingface_hub`/`gradio deploy`).
+
+**Out of scope (recorded in `ROADMAP.md`, not implemented):** Engine B (hand-crafted connected FIGlet-style fonts), ANSI color, animation, image-to-ASCII.
+
+## File tree
+
+```
+Khatt/
+├── pyproject.toml            # all metadata + ruff/mypy/pytest/coverage config
+├── uv.lock                   # committed
+├── LICENSE                   # MIT (code only)
+├── README.md                 # demo media, install, quickstart, FIGlet comparison, Spaces deploy
+├── CHANGELOG.md              # Keep a Changelog
+├── CONTRIBUTING.md
+├── ROADMAP.md                # out-of-scope items above
+├── PLAN.md                   # this document
+├── app.py                    # single-file Gradio app
+├── .gitignore
+├── .pre-commit-config.yaml   # ruff, ruff-format, trailing-whitespace, end-of-file-fixer, uv lock --check
+├── .github/workflows/ci.yml  # runs on push to GitHub (later); + release.yml in PR 6 (disabled)
+├── khatt/
+│   ├── __init__.py           # render(), list_fonts(), list_styles(), __version__
+│   ├── py.typed
+│   ├── shaping.py
+│   ├── raster.py
+│   ├── mapper.py
+│   ├── cli.py
+│   └── fonts/
+│       ├── __init__.py       # font registry
+│       ├── Amiri-Regular.ttf, Cairo-Bold.ttf, NotoNaskhArabic-Regular.ttf, Rubik-Bold.ttf
+│       └── LICENSES/         # OFL texts per family
+└── tests/
+    ├── conftest.py           # --update-golden pytest option, shared fixtures
+    ├── test_shaping.py
+    ├── test_raster.py
+    ├── test_mapper.py
+    ├── test_api.py
+    ├── test_cli.py
+    ├── test_edge_cases.py
+    └── golden/               # word × style × font snapshots (*.txt)
+```
+
+Note: spec calls for flat `khatt/` package paths, so the build config uses flat layout rather than `uv init --package`'s default `src/` layout.
+
+## Dependencies
+
+| Package | Why | Group |
+|---|---|---|
+| `uharfbuzz` | Real shaping engine: positional forms, mandatory ligatures, kerning — the reason Khatt can exist. Wheels on all target platforms/versions. | runtime |
+| `freetype-py` | Rasterizes glyphs **by glyph ID** at HarfBuzz positions (Pillow can't). Bundles libfreetype → deterministic cross-platform output. *(The one dep beyond your list — approved.)* | runtime |
+| `python-bidi` | UBA run ordering for mixed Arabic/Latin/digit strings. | runtime |
+| `Pillow` | Canvas compositing, downsampling, PNG output. | runtime |
+| `typer` | CLI. | runtime |
+| `gradio` | App only — optional extra `khatt[app]`, not a base install requirement. | extra |
+| `pytest`, `pytest-cov` | Test suite + coverage gate (`--cov-fail-under=85`). | dev |
+| `ruff`, `mypy`, `pre-commit` | Lint/format, type-check, hooks. | dev |
+| `twine` | `twine check dist/*` packaging validation in PR 6. | dev |
+
+Not used: `arabic-reshaper` — unnecessary given uharfbuzz works; noted in README as the inferior fallback approach.
+
+Python 3.10–3.13. Everything through `uv` (`uv add`, `uv run`, `uv build`); `uv.lock` committed.
+
+## Git workflow (local-mode adaptation)
+
+`git init` with `main`; **never commit to main directly**. Each phase = one branch (`chore/scaffold`, `feat/shaping`, …), Conventional Commits throughout. Since there's no remote yet: each phase merges to main locally with `--no-ff` and a PR-style merge commit body (what changed / how tested / tradeoffs) — preserving reviewable history so branches can be pushed and retro-PR'd when you connect GitHub. The "before every push" gate becomes **before every merge to main**: `uv run ruff check .` + `uv run ruff format --check .` + `uv run mypy khatt` + `uv run pytest` — never merge red. CI workflow files are committed from PR 1 and will run on first GitHub push.
+
+## Milestones → branches
+
+1. **`chore/scaffold`** — uv project (flat layout), full `pyproject.toml` (metadata, scripts, ruff/mypy/pytest/coverage config), `.pre-commit-config.yaml`, `ci.yml` (matrix: py 3.10–3.13 × ubuntu/windows; ruff → mypy → pytest+coverage), MIT LICENSE, empty package skeleton + placeholder test, PLAN.md, ROADMAP.md. Gate green on empty suite.
+2. **`feat/shaping`** — tests first: lam-alef ligature (glyph count + name), «محمد» positional forms (`.init/.medi/.fina` glyph-name assertions), mixed-direction visual order, tashkeel flag behavior. Then `shaping.py` until green.
+3. **`feat/raster-mapper`** — download/bundle 4 fonts + OFL licenses; `raster.py` (deterministic output, grid-dimension tests, all-fonts-load test); `mapper.py` (ramp-membership, monotonicity, threshold tests); golden harness (`--update-golden` in conftest) + goldens for «مرحبا» «خط» «القاهرة» × 3 styles × Amiri.
+4. **`feat/api-cli`** — `render()` + `cli.py`, `typer.testing.CliRunner` tests (flags, stdin, txt/png output, non-Arabic warning path), edge-case suite (empty, single letter, long-vs-width, tashkeel-only, emoji → graceful warning), coverage gate ≥85% enforced.
+5. **`feat/gradio-app`** — `app.py` + `[app]` extra + README Spaces-deploy section. Manual verification: `uv run --extra app python app.py`.
+6. **`docs/release-0.1`** — README (Arabic demo media at top, install, API/CLI/Gradio quickstarts, FIGlet comparison), CHANGELOG, CONTRIBUTING, `uv build` + `twine check dist/*`, clean-venv wheel install smoke test (`khatt "مرحبا"`), tag `v0.1.0`. `release.yml` (PyPI trusted publishing) committed **but not enabled** — needs your go-ahead + a GitHub remote anyway.
+
+## Test strategy
+
+- **Shaping (critical):** glyph-name-based assertions via HarfBuzz — ligature presence, positional-form suffixes, run order for mixed-direction input, tashkeel flag. No pixels involved → fast and unambiguous.
+- **Raster:** byte-identical output for pinned inputs (determinism guaranteed by bundled fonts + wheel-bundled libfreetype + `uv.lock`); exact grid dimensions per requested width; every bundled font loads and renders non-empty ink.
+- **Mapper:** output charset ⊆ declared ramp per style; synthetic gradient input → monotonic density; threshold semantics.
+- **Golden files:** committed snapshots under `tests/golden/`, diffed on every run; regenerate deliberately via `pytest --update-golden`. If a platform-specific diff ever appears despite the determinism design, fallback is documented in conftest: per-platform goldens for the offending case.
+- **CLI:** `CliRunner` — every flag, stdin, file outputs, error paths.
+- **Edge cases:** empty string, single letter, long string vs width, tashkeel-only string, emoji/unsupported chars → warning + graceful degradation, never a crash.
+- **Coverage:** `pytest-cov`, `--cov=khatt --cov-fail-under=85` in config and CI.
+
+## Definition of done
+
+All six phases merged to main via the local gate, coverage ≥85%, `uv build` yields valid wheel+sdist (`twine check` passes), wheel installed into a clean venv runs `khatt "مرحبا"` with correct connected-script output, `app.py` runs locally, CI workflows committed and ready for first GitHub push, tag `v0.1.0`.
+
+## Open questions
+
+1. **Tashkeel default:** I propose **strip by default** (diacritics are noise at grid resolution) with `--keep-tashkeel` / `tashkeel=True` to render them. OK, or prefer keep-by-default?
+2. **PyPI name:** `khatt` availability on PyPI is unverified (no network check done in planning). If taken at release time: fallback candidates `khatt-art`, `pykhatt` — your call then; doesn't block PRs 1–5.
+3. **Fourth font:** Rubik chosen for strong Latin+Arabic dual coverage (good for mixed strings). Swap for something else (e.g. Lateef, Reem Kufi) if you'd rather.
+4. **Terminal cell aspect:** default 0.5 (cell twice as tall as wide) — standard assumption, exposed as an internal constant, not a public API param in v0.1.0.