# diora-tui EPUB-Reader im Terminal — die erste Stufe einer TUI-Version von diora. Zeigt ein Buch als **eine durchgehende Ansicht** über alle Kapitel hinweg (wie diora's Web-Reader), nicht Kapitel für Kapitel. Lesefortschritt wird als dieselbe `"blockIndex:innerFraction"`-Positionsangabe geführt wie der Web-Reader (`books/models.py`, `EBookProgress`) — `blockIndex` zählt dabei exakt wie `static/js/app.js`s `EPUB_BLOCK_SELECTOR` (`p, h1-h6, li, blockquote, dt, dd, figcaption` + textbasierte `div`s ohne Element-Kinder), fortlaufend über das ganze Buch. Dadurch ist die Position zwischen TUI und Web-Reader direkt vergleichbar, und `diora-tui sync` kann Fortschritt in beide Richtungen synchronisieren (siehe unten). Die Lesestelle folgt dem Vertrag aus `docs/progress-sync.md`: **die zuletzt gelesene Stelle gewinnt** (auf welchem Gerät auch immer), die weiteste bleibt als Hinweis erhalten. Die Regeln stehen in `progress.py` und sind dieselben wie auf dem Server und in den Apps. ## Setup ```bash cd tui pip install -e . ``` ## Nutzung ```bash diora-tui --library ~/Books # Standard: ~/Books ``` Tastenkürzel: - `↑`/`k`, `↓`/`j` — zeilenweise scrollen - `n` — nächstes Kapitel, `p` — vorheriges Kapitel - `w` — zur weitesten Stelle des Buchs springen (auf Wunsch; beim Öffnen weist ein Hinweis darauf hin) - `f` — Fußnote in der Nähe der aktuellen Position anzeigen (Peek-Overlay, `Escape`/`f`/`q` zum Schließen); Erkennung folgt derselben Heuristik wie `app.js`s `_looksLikeFootnoteLink` (Link in/um ``, Klassenname mit note/footnote/fn, oder `epub:type="noteref"`) - `Enter` — markiertes Buch aus der Bibliothek öffnen - `r` (in der Bibliothek) — gelesene Bücher ein-/ausblenden (siehe unten) - `Escape` / `q` — zurück zur Bibliothek (im Reader) bzw. beenden (in der Bibliothek) Der Fließtext ist auf 120 Zeichen Breite begrenzt und horizontal zentriert (lesbarer als volle Terminalbreite bei breiten Fenstern). Unten rechts zeigt eine Statusleiste Akkustand (falls vorhanden, via `psutil`) und Uhrzeit, sekündlich aktualisiert, auf Bibliotheks- und Reader-Ansicht. Die Bibliotheksansicht ist nach der zuletzt gelesenen Stelle sortiert (neueste zuerst, auch was auf einem anderen Gerät gelesen wurde), zeigt den Lesestand in % und blendet gelesene Bücher standardmäßig aus (`r` zeigt sie, für diese Sitzung). Bücher vom Server stehen mit ☁ in der Liste, bevor sie heruntergeladen sind. ## Anmelden und synchronisieren ```bash diora-tui login # einmal; fragt Benutzername und Passwort diora-tui # die Oberfläche, synct beim Start und beim Beenden diora-tui sync # nur abgleichen, ohne Oberfläche diora-tui logout # gespeicherte Zugangsdaten löschen ``` `login` meldet sich wie die Apps über das Web-Formular an, liest den vorhandenen API-Token von der Einstellungsseite (es wird nie ein neuer erzeugt: das würde die Apps abmelden) und leitet den Buchschlüssel aus dem Passwort ab (PBKDF2, wie „Mit Passwort entsperren“ im Web). Das Passwort wird nicht gespeichert. Passt der abgeleitete Schlüssel nicht (Passwort seit dem Hochladen geändert, Schlüssel zufällig erzeugt), fragt `login` nach dem Schlüssel (diora: Einstellungen → Schlüssel kopieren; `--paste-key` fragt gleich danach). Token und Schlüssel liegen geschützt in `config.json`: unter Windows per DPAPI (nur dieser Windows-Benutzer auf diesem Rechner kann sie lesen), sonst als Base64 in einer 0600-Datei. Eine ältere Konfiguration mit Klartextfeldern wird beim ersten Lesen geschützt neu geschrieben. Alle Dateien liegen unter `platformdirs`' Verzeichnissen; `DIORA_TUI_HOME=` legt sie stattdessen gemeinsam in einen Ordner (zweites Konto, Tests). **Was synchronisiert wird:** die Bücherliste (`GET /books/`, ohne die Blobs der Markierungen) samt Lesestand, Gelesen-Status und der Uhr des Servers. Die Bücher selbst werden erst beim Öffnen geladen und entschlüsselt (` - .epub` im Bibliotheksordner). PDFs werden übersprungen. **Lesestand** (`progress.py`, `reader_screen.py`): - Gespeichert wird nur, was der Leser selbst bewegt hat (Tasten, Mausrad), mit dem Zeitpunkt des Ankommens (`read_at`). Wiederherstellen, Umbruch bei Größenänderung und Sprünge auf Angebote ändern nichts. Ein offenes, ruhendes Buch kann deshalb nie eine neuere Stelle von woanders überschreiben. - Zeiten sind Serverzeit: die TUI lernt aus jeder Antwort den Versatz ihrer Uhr, und der Server korrigiert mit `sent_at` nach. Ein falsch gehender Rechner ordnet trotzdem richtig. - Jede Stelle wird lokal angewendet und vorgemerkt (`pending`, je Buch die später gelesene), bis der Server sie hat, auch offline; nach einem Abgleich wird sie nach derselben Regel auf den Stand des Servers gelegt. - Alle zwei Minuten fragt ein offenes Buch den Server. Liegt dort eine neuere Stelle von einem anderen Gerät, fragt die TUI „Auf *X* weitergelesen — bei n %. Springen?“ (`y`/`n`), und bewegt sich nie von allein. - Der Fortschritt in % ist wie im Web der Anteil am Buchtext in Zeichen (`blocks.fraction_for_anchor`), nicht mehr 0. ## Performance bei großen Büchern Sehr große Bücher (mehrstellige Tausend Absätze — z.B. Sammelbände) können beim *ersten* Öffnen mehrere Sekunden bis niedrige zweistellige Sekunden brauchen (Parsing + Zeilenumbruch-Berechnung für die durchgehende Ansicht). Ein zweites Öffnen desselben Buchs bei gleicher Terminalbreite ist dank Cache (`~/.cache/diora-tui/layout_cache/`) deutlich schneller. Das Rendering selbst skaliert nicht mit der Buchgröße — nur die tatsächlich sichtbaren Zeilen werden gezeichnet (Textual Line API), nicht das ganze Buch auf einmal. ## Tests und Anker-Parität mit dem Web-Reader ```bash pip install -e . pytest pytest tests # Blockliste, Anker, App-Start (Textual-Pilot) ``` Die Position ist ein Block-Index, den alle Clients gleich zählen müssen. Ob die TUI das tut, prüft `tools/parity/` gegen den echten Web-Code (`parseEpub` aus `static/js/app/40-epub.js` in headless Chromium): ```bash NODE_PATH=/node_modules PLAYWRIGHT_BROWSERS_PATH=... node tools/parity/web_blocks.cjs web.json buch1.epub buch2.epub python tools/parity/compare_blocks.py web.json ``` Stand 2026-10-26 (6 Bücher, bis 25.798 Blöcke): Anzahl, Tags, Text, Zeichenposition und -länge aller Blöcke sowie die Gesamtlänge sind identisch. Das setzt voraus, dass die TUI den EPUB-Inhalt wie der Browser liest: UTF-8-dekodiert, mit dem HTML5-Parser (`html5lib`, nicht libxml2) und aus den Rohdaten (`item.content`; `get_content()` von ebooklib formatiert um und fügt Leerraum ein). ## Grenzen der aktuellen Version - Nur EPUB, kein PDF (der Abgleich überspringt PDFs und meldet sie). - Text wird als Fließtext ohne Bild-/Layout-Rendering dargestellt. - `innerFraction` (die Position *innerhalb* eines Blocks) ist eine Terminal-Näherung (zeilenbasiert statt pixelbasiert wie im Browser) — für die Fortschritts-Sortierung zählt primär `blockIndex`, der exakt mit dem Web-Reader übereinstimmt; `innerFraction` ist nur ein Tiebreaker innerhalb desselben Blocks.