# Wiki di Bookish

## Guida all'uso

### Convertitore

1. Apri la homepage di Bookish
2. Trascina un file nell'area di upload, oppure clicca per selezionarlo
3. Scegli il formato di destinazione cliccando su un bottone
4. Clicca **Converti**
5. La barra di progresso mostra lo stato della conversione
6. A conversione completata, clicca **Scarica file**
7. Opzionale: clicca **Leggi nel reader** per visualizzare il file convertito

### Formati supportati

| Input | Output |
|---|---|
| EPUB | EPUB, MD, DOCX, PDF, TXT, HTML, FB2, LaTeX |
| PDF | EPUB, MD, DOCX, TXT, HTML, LaTeX |
| DOCX | EPUB, MD, PDF, TXT, HTML, LaTeX |
| Markdown | EPUB, DOCX, PDF, TXT, HTML, LaTeX |
| TXT | EPUB, MD, DOCX, PDF, HTML, LaTeX |
| HTML | EPUB, MD, DOCX, PDF, TXT, LaTeX |
| FB2 | EPUB, MD, DOCX, PDF, TXT, HTML, LaTeX |
| LaTeX | EPUB, MD, DOCX, PDF, TXT, HTML |

### Reader — Operazioni base

1. Vai su **Reader** nella navigazione
2. Trascina un ebook (EPUB, PDF, MD, TXT, HTML, FB2, DOCX) o clicca per caricarlo
3. Usa la toolbar per:

   | Pulsante | Azione |
   |---|---|
   | **☰** | Apri/chiudi indice laterale |
   | **⇔** | Slider larghezza area di lettura (40–100%) |
   | **A− / A+** | Zoom font |
   | **☀️ / 🌙 / 🟤** | Cambia tema (chiaro/scuro/seppia) |
   | **🔍** | Cerca nel testo |
   | **🔖** | Aggiungi segnalibro alla posizione corrente |
   | **⛶** | Schermo intero |
   | **?** | Aiuto e scorciatoie da tastiera |

4. Naviga con le frecce **← →** della tastiera
5. La **posizione di lettura** viene salvata automaticamente (locale + server)

### Reader — Segnalibri

- Premi **🔖** nella toolbar o **Ctrl+B** / **⌘B** per aggiungere un segnalibro
- Un toast di conferma appare in basso e il pulsante fa un piccolo "pulse"
- Vai nella sidebar **☰ → Segnalibri** per vedere l'elenco
- **Clicca** su un segnalibro per tornarci
- Premi **✕** per eliminarlo
- I segnalibri sono salvati su server SQLite + localStorage (fallback)
- Lo stesso libro ha sempre gli stessi segnalibri, anche su PC diverso

### Reader — Scorciatoie da tastiera

| Tasti | Azione |
|---|---|
| **←** / **→** | Pagina precedente/successiva |
| **Ctrl+B** / **⌘B** | Aggiungi segnalibro |
| **Ctrl+F** / **⌘F** | Cerca nel libro |
| **+** / **-** | Zoom avanti/indietro |
| **F** | Schermo intero |
| **Esc** | Chiudi help modal / Esci da fullscreen |

### Reader — Slider larghezza

La barra a destra nella toolbar (con icona ⇔) regola la larghezza dell'area di lettura dal 40% al 100% dello schermo. Utile per file con righe molto lunghe o per preferenze personali di lettura. L'impostazione viene salvata in localStorage.

## API Endpoints

### Endpoints pubblici

| Metodo | Path | Descrizione |
|---|---|---|
| POST | `/upload` | Carica file e avvia conversione |
| GET | `/progress/<task_id>` | SSE stream progresso |
| GET | `/download/<filename>` | Scarica file convertito |
| GET | `/formats?input=<ext>` | Formati disponibili per input |
| GET | `/reader` | Pagina reader |
| GET | `/reader/<filename>` | Reader per file specifico |
| GET | `/reader/serve/<filename>` | Serve il file al reader |
| GET | `/reader/formats` | Formati supportati dal reader |

### API REST (bookmarks e posizioni)

| Metodo | Path | Descrizione |
|---|---|---|
| GET | `/api/bookmarks/<content_hash>` | Recupera tutti i segnalibri del libro |
| POST | `/api/bookmarks` | Aggiunge un segnalibro |
| DELETE | `/api/bookmarks/<id>` | Elimina un segnalibro |
| GET | `/api/position/<content_hash>` | Recupera l'ultima posizione di lettura |
| PUT | `/api/position/<content_hash>` | Salva la posizione di lettura (body JSON) |

## Domande frequenti

**D: Che qualità ha la conversione?**
R: Pandoc preserva titoli, grassetto/corsivo, elenchi, tabelle semplici e immagini. Per layout complessi (es. PDF con colonne multiple) la fedeltà dipende dalla complessità del file originale.

**D: I file vengono conservati?**
R: I file in `uploads/` e `converted/` vengono cancellati dopo 1 ora. Usa il download subito dopo la conversione. I segnalibri e le posizioni di lettura sono invece permanenti in `bookish.db`.

**D: I segnalibri restano se ricarico lo stesso libro?**
R: Sì. I segnalibri sono legati al contenuto del file (SHA256), non al nome o all'UUID di upload. Stesso file = stessi segnalibri.

**D: Posso usare i segnalibri da un altro PC?**
R: Sì, se sei sulla stessa LAN e raggiungi lo stesso server. I segnalibri sono salvati su SQLite, non nel browser.

**D: Quanto spazio serve?**
R: Minimo. L'app stessa è ~5MB. Pandoc binary incluso ~35MB extra. Il database SQLite occupa pochi KB.

**D: Posso usarlo su mobile?**
R: Il convertitore è responsive. Il reader funziona ma non è ottimizzato per schermi piccoli.

**D: Come cambio la secret key?**
R: Imposta `BOOKISH_SECRET` come variabile d'ambiente prima di avviare.

## Sicurezza

- Uso personale — nessuna autenticazione implementata
- File validati per estensione all'upload
- Path traversal prevenuto con `os.path.basename()` e `secure_filename()`
- MIME types controllati al download
- Limite file a 50MB
- Pulizia automatica file temporanei dopo 1h