diora-web/tui/README.md

# 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 `<sup>`, Klassenname mit note/footnote/fn, oder
  `epub:type="noteref"`)
- Bibliothek: `Enter` öffnet das markierte Buch, `c` das Buch der „Weiterlesen“-Karte, `1`–`4`
  Status (Alle · Angefangen · Ungelesen · Gelesen), `o` Ordner, `/` Suche, `s` Sortierung,
  `m` Bücher ⇄ Zeitschriften, `Escape` setzt Suche und Filter zurück. Chips und Karte lassen
  sich auch anklicken.
- `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 Bibliothek

Wie die Bibliothek im Web (`docs/library.md`), nur im Terminal:

- **Weiterlesen-Karte** oben (Titel, Autor, Balken, „Seite 132 von 186“, wann und auf welchem
  Gerät zuletzt gelesen) und darunter die Bücher, die davor gelesen wurden. Das Buch der Karte
  steht nicht noch einmal in der Liste. Bei Suche und Filtern entfällt die Karte.
- **Chips:** Alle · Angefangen · Ungelesen · Gelesen (mit Anzahl), dann die Ordner in der
  Reihenfolge, die im Web eingestellt ist (verschlüsselte Bibliothekseinstellungen), und
  „Ohne Ordner“. Ein Buch kann in mehreren Ordnern stehen.
- **Suche** in Titel und Autor, ohne Beachtung von Groß-/Kleinschreibung und Akzenten.
- **Sortierung:** Zuletzt · Titel · Autor · Neu hinzugefügt · Kürzeste/Längste zuerst (Zahlen
  nach Wert: „Band 2“ vor „Band 10“). Sie bleibt gespeichert.
- **Länge:** die Seitenzahl aus den Metadaten (`pages`); fehlt sie, rechnet die TUI sie für
  schon geladene Bücher einmal aus dem Text aus (1800 Zeichen je Seite, wie der Web-Reader), wenn
  nach Länge sortiert wird („Länge wird ermittelt …“). Nicht geladene Bücher ohne Länge stehen am
  Ende. Zurück auf den Server schreibt die TUI die Länge nicht; das macht der Web-Reader.
- **Bücher ⇄ Zeitschriften** (`m`): Zeitschriften sind, was in den Metadaten so markiert ist
  oder im Ordner „Zeitschriften“/„Magazine“ liegt. Die Heft-Ansicht mit Artikeln gibt es in der
  TUI nicht; ein Heft ist ein Buch.
- ☁ vor dem Titel: auf dem Server, noch nicht geladen. ✓: gelesen.

Nicht in der TUI: Serien-Stapel, Ausgaben (mehrere Fassungen eines Werks stehen einzeln),
Cover, Ordner anlegen/zuweisen, Eingang aus der Cloud.

## 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=<Ordner>` 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 (`<id> - <Titel>.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=<diora-web>/node_modules PLAYWRIGHT_BROWSERS_PATH=...   node tools/parity/web_blocks.cjs <diora-web> 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.